{
  "openapi": "3.1.0",
  "info": {
    "title": "FlowZap API",
    "version": "1.3.0-preview.20261116",
    "summary": "WhatsApp para equipes e integrações — API HTTP.",
    "description": "API HTTP do FlowZap para enviar e receber mensagens de WhatsApp, administrar números, grupos, canais, contatos e integrações.\n\nFlowZap é um produto FlowPost (flowpost.com.br). Endereço de produção: `https://flowzap.flowpost.com.br`, com todas as rotas em `/v1`. Integração não oficial, sem parceria ou endosso da Meta ou do WhatsApp.\n\n## Autenticação\n`Authorization: Bearer fzk_…`. Chaves antigas com o prefixo `fbk_` continuam funcionando. Cada chave pertence a uma organização, pode ficar presa a uma área de trabalho ou a um número, e tem escopos (`x-scopes` em cada rota): `workspaces:read`, `instances:read`, `instances:write`, `messages:send`, `messages:read`, `webhooks:read`, `webhooks:write`, `engine:read`, `engine:write`, `account:read`, `crm:read`, `crm:write`, `campaigns:read`, `campaigns:write`, `calls:read`, `calls:write`, `calls:recordings` (baixar e apagar gravações de ligações), `calls:admin` (administrar as ligações da conta: origens do áudio no navegador e números de teste do piloto; só em chaves da organização inteira, de dona ou administradora da conta inteira, guardadas no servidor; nunca concedido por OAuth), `team:read`, `team:write`, `billing:read`, `billing:write`, `audiences:read`, `audiences:write`, `audiences:export`. Rotas que já existiam continuam aceitando o escopo antigo: CRM e respostas rápidas aceitam `engine:*` ou `crm:*`; campanhas, `messages:*` ou `campaigns:*`; ligações, `engine:write` ou `calls:write`; lista de números, estado, limites, fila e capacidades do número aceitam também `instances:read` (o telefone completo do próprio número, `phone`, só aparece com `instances:read`). Eventos: `engine:read` lê todos; `calls:read` só `call.*` (inclusive `call.recording_*`); `crm:read` só `ticket.*`, `lead.stage_changed` e `csat.answered`.\n\n## Modelo de operação\nRotas que precisam do WhatsApp (grupos, perfil, contatos, conversas, canais…) viram uma operação executada pelo número. A API espera até 15 s: **200** com `data` quando terminou, **202** com `Location: /v1/operations/{id}` quando ainda roda, **422** quando o WhatsApp recusou, **502** quando o resultado é incerto (não repita às cegas; `retryable: false`), **504** quando venceu sem ser executada. Todo 202 traz `Retry-After: 1` (segundos até consultar de novo); `GET /v1/operations/{id}?envelope=1` responde sempre 200 com `{data: {id, kind, state, result, error, …}}`, para quem prefere não tratar cada estado por status HTTP. Envio de mensagens é diferente: **202** na fila, e o resultado chega pelos eventos `message.*`.\n\n## Idempotência\n`Idempotency-Key` é obrigatória em `POST …/messages`, `POST …/messages/template`, `POST …/scheduled-messages`, `POST …/campaigns`, `POST /v1/workspaces/{id}/instances`, `POST /v1/team/invitations`, `POST /v1/billing/checkout/*`, `POST /v1/billing/addons/calls`, `POST /v1/billing/addons/recordings`, `POST /v1/billing/subscription/renewal` (UUID), `POST …/calls/{callId}/answer|decline|hangup|mute` e `POST /v1/webhook-endpoints/{id}/rotate-secret`, e aceita nas operações. Repetir com a mesma chave devolve o mesmo resultado (`Idempotent-Replay: true`); com outro conteúdo, 409 `idempotency_conflict`.\n\n## Erros\nSempre `{\"error\": {\"code\", \"message\", \"request_id\", \"retryable\"}}`. 501 `not_supported_by_engine` marca recursos que o WhatsApp Web não oferece (`x-status: not_supported`). O catálogo completo (código → status → significado → repetir? → o que fazer) está em `docs/api/erros.md` e na seção \"Catálogo de erros\" de `/docs`; `code` é estável, `message` pode mudar.\n\nToda resposta traz `X-Request-Id`: envie o seu (8 a 128 caracteres entre letras, números e `. _ : -`) ou o FlowZap gera um UUID. `error.request_id` é o mesmo valor, registrado no log de erros; informe-o ao suporte. `retryable` segue uma regra única: 429 é `true` e vem sempre com `Retry-After` (exceto cotas do plano: `draft_limit_reached`, `slot_limit_reached`, `workspace_slot_limit_reached`); 501 é `false`; 502 de resultado incerto é `false` (confira antes); 503 e 504 são `true`; os demais 4xx são `false`.\n\n## Versões e mudanças\n`info.version` traz a data (`<semver>-preview.<AAAAMMDD>`). Mudanças aditivas (rotas, campos, eventos, códigos de erro) entram sem aviso prévio: ignore campos e eventos que não conhece. Remoções ou mudanças incompatíveis só em nova versão maior, com pelo menos 90 dias de aviso (cabeçalhos `Deprecation`/`Sunset` e `deprecated: true`). Histórico em `docs/api/CHANGELOG.md`; contrato único em `/openapi.json` e `/openapi.yaml`, coleção Postman em `/flowzap.postman_collection.json`. Reconciliação após falhas e quedas: `docs/api/reconciliacao.md`. Ligações ao vivo (softphone ou central de atendimento): `docs/api/guia-ligacoes.md`.\n\n## Limites\nA API está em todos os planos (sem o recurso `api` no plano: 403 `plan_feature_required`). Pedidos por minuto conforme o plano, somando todas as chaves da organização: toda resposta traz `RateLimit-Limit`, `RateLimit-Remaining` e `RateLimit-Reset` (segundos); acima do limite, 429 `rate_limited` + `Retry-After`. Plano, limites e uso em `GET /v1/account`.\n\nEnvio: 60 por minuto com rajada de 10, por chave e número (429 `rate_limited` + `Retry-After`); envios aguardando na fila do número conforme o plano (429 `queue_full`). Webhooks ativos por área de trabalho e pessoas da equipe também seguem o plano. Corpo JSON até 1 MB nas rotas de número; mídia até 16 MiB (upload binário)."
  },
  "servers": [
    {
      "url": "https://flowzap.flowpost.com.br",
      "description": "Produção."
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Áreas de trabalho e operações",
      "description": "Áreas de trabalho visíveis para a chave e o resultado de operações que responderam 202."
    },
    {
      "name": "Números",
      "description": "Criar, conectar por QR code, desconectar e excluir números; fila de envios, intervalo entre envios e proxy."
    },
    {
      "name": "Mensagens e mídia",
      "description": "Envio de todos os tipos de mensagem, consulta do envio, upload e download de mídia."
    },
    {
      "name": "Conversas e etiquetas",
      "description": "Leitura das conversas pelo histórico do FlowZap, ações de conversa e de mensagem, etiquetas do WhatsApp."
    },
    {
      "name": "Grupos e comunidades",
      "description": "Criar e administrar grupos, convites, participantes, pedidos de entrada e comunidades."
    },
    {
      "name": "Contatos e perfil",
      "description": "Contatos, verificação de números, bloqueio, perfil do número, privacidade e presença."
    },
    {
      "name": "Canais",
      "description": "Canais do WhatsApp: criar, seguir, ler, reagir e publicar."
    },
    {
      "name": "Perfil comercial",
      "description": "Leitura de perfis comerciais. Catálogo e edição do perfil não existem no WhatsApp Web."
    },
    {
      "name": "Eventos, webhooks e SSE",
      "description": "Eventos em ordem por número, fluxo SSE, mensagens recebidas e cadastro de webhooks."
    },
    {
      "name": "CRM e respostas rápidas",
      "description": "Leads com consentimento, etiquetas de lead, anotações e respostas rápidas."
    },
    {
      "name": "Funil e atendimentos",
      "description": "Funil de contatos por etapa (kanban), campos personalizados, atendimentos Abertos/Resolvidos com responsável e a pesquisa de satisfação (nota de 1 a 5)."
    },
    {
      "name": "Respostas automáticas",
      "description": "Boas-vindas, fora do horário, menu numerado, palavras-chave e a pesquisa de satisfação de cada número. Só respondem quem escreveu primeiro, nunca em grupos."
    },
    {
      "name": "Públicos",
      "description": "Públicos de anúncios: participantes dos grupos do número exportados para o Meta e o Google, com declaração de base legal (LGPD). Ninguém do público recebe mensagem."
    },
    {
      "name": "Modelos e agendamentos",
      "description": "Modelos de mensagem (avisos, cobranças, lembretes) com variáveis, envio por modelo na hora ou agendado, e mensagens avulsas agendadas."
    },
    {
      "name": "Lançamento em grupos",
      "description": "Mensagem para vários grupos que o número administra e links públicos que enchem os grupos em ordem."
    },
    {
      "name": "Campanhas",
      "description": "Envio em massa só para contatos com consentimento registrado."
    },
    {
      "name": "Chatwoot, n8n e Make",
      "description": "Integração nativa com o Chatwoot. n8n e Make usam os webhooks e a API (guias em docs/integracoes)."
    },
    {
      "name": "Equipe",
      "description": "Pessoas e convites da organização, com as regras da tela Equipe do console. A chave age por quem a criou."
    },
    {
      "name": "Cobrança",
      "description": "Assinatura, ofertas, ligações e pagamentos; o pagamento acontece no checkout do Asaas (a resposta traz o link)."
    },
    {
      "name": "Ligações",
      "description": "Beta: fazer, atender, recusar, desligar e silenciar ligações (com áudio por WebSocket), escolher os números com ligações, liberar as origens do áudio no navegador, definir os números de teste do piloto e ver se um número está pronto para ligações."
    },
    {
      "name": "Convite de dono",
      "description": "Página do console para aceitar o convite de dono enviado pela equipe FlowZap. Sem chave de API: o link do e-mail é a prova."
    },
    {
      "name": "Conteúdo público",
      "description": "Sem chave de API: o que está publicado no blog, glossário, comparativos, segmentos e autores do site, e as listas do sitemap, do RSS e do llms.txt."
    }
  ],
  "paths": {
    "/v1/public/content/items": {
      "get": {
        "summary": "Listar conteúdos publicados",
        "operationId": "get-v1-public-content-items",
        "description": "**Sem chave de API.** Lista paginada (20 por página) do que está publicado, do mais recente para o mais antigo. Filtros opcionais por tipo e por palavra-chave (`tag`). Usada pelo site para montar `/blog`, `/glossario`, `/comparativos` e `/segmentos`.\n\nSem autenticação por chave de API.",
        "tags": [
          "Conteúdo público"
        ],
        "x-scopes": [],
        "security": [],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "article",
                "glossary",
                "comparison",
                "segment"
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 1
            }
          },
          {
            "name": "tag",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Página de cartões: `data`, `page`, `per_page`, `total`, `total_pages`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "page",
                    "per_page",
                    "total",
                    "total_pages"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "page": {
                      "type": "integer"
                    },
                    "per_page": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "total_pages": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/public/content/items/{type}/{slug}": {
      "get": {
        "summary": "Ler um conteúdo publicado",
        "operationId": "get-v1-public-content-item",
        "description": "**Sem chave de API.** O conteúdo publicado com o HTML já sanitizado (`html`), sumário (`toc`), tempo de leitura, TL;DR, perguntas frequentes, fontes, autor e revisor, capa (`cover.path` é o caminho no próprio site; `cover.og_url` é JPEG 1200×630), até 3 relacionados e o JSON-LD pronto (`json_ld`). Alterações ainda não publicadas nunca aparecem.\n\nSem autenticação por chave de API.",
        "tags": [
          "Conteúdo público"
        ],
        "x-scopes": [],
        "security": [],
        "parameters": [
          {
            "name": "type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "article",
                "glossary",
                "comparison",
                "segment"
              ]
            }
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "O conteúdo publicado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error",
            "description": "`not_found`: não existe ou não está publicado."
          }
        }
      }
    },
    "/v1/public/content/authors/{slug}": {
      "get": {
        "summary": "Ler um autor",
        "operationId": "get-v1-public-content-author",
        "description": "**Sem chave de API.** Nome, bio, credenciais (`role_title`), foto (`photo_url`), perfis (`same_as`) e os conteúdos publicados do autor.\n\nSem autenticação por chave de API.",
        "tags": [
          "Conteúdo público"
        ],
        "x-scopes": [],
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "O autor e seus conteúdos publicados.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error",
            "description": "`not_found`"
          }
        }
      }
    },
    "/v1/public/content/sitemap-entries": {
      "get": {
        "summary": "Entradas do sitemap",
        "operationId": "get-v1-public-content-sitemap-entries",
        "description": "**Sem chave de API.** Todo conteúdo publicado e indexável, com `updated_at` e a imagem de capa, para o `sitemap.xml` do site.\n\nSem autenticação por chave de API.",
        "tags": [
          "Conteúdo público"
        ],
        "x-scopes": [],
        "security": [],
        "responses": {
          "200": {
            "description": "`data`: lista de `{type, slug, path, url, title, published_at, updated_at, image}`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/public/content/feed-entries": {
      "get": {
        "summary": "Entradas do feed RSS",
        "operationId": "get-v1-public-content-feed-entries",
        "description": "**Sem chave de API.** Os 50 artigos publicados mais recentes, para o `rss.xml` do site.\n\nSem autenticação por chave de API.",
        "tags": [
          "Conteúdo público"
        ],
        "x-scopes": [],
        "security": [],
        "responses": {
          "200": {
            "description": "`data`: lista de `{type, slug, path, url, title, summary, author, published_at, updated_at, image}`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/public/content/llms-entries": {
      "get": {
        "summary": "Entradas do llms.txt",
        "operationId": "get-v1-public-content-llms-entries",
        "description": "**Sem chave de API.** Título, endereço, resumo e TL;DR de cada conteúdo publicado e indexável, para o `llms.txt` e o `llms-full.txt` do site.\n\nSem autenticação por chave de API.",
        "tags": [
          "Conteúdo público"
        ],
        "x-scopes": [],
        "security": [],
        "responses": {
          "200": {
            "description": "`data`: lista de `{type, slug, path, url, title, summary, tldr, updated_at}`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/operations/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Consultar uma operação",
        "operationId": "get-v1-operations-id",
        "description": "Resultado de uma operação que respondeu 202. Mesmo formato da resposta original: 200 com `data`, 202 enquanto roda (com `Retry-After: 1`: espere ao menos 1 s antes de perguntar de novo), 422/502/504 se terminou sem sucesso. Resultados com dados de pessoas (`group.list`, `group.info`, `contact.list`, `contact.check`, `contact.avatar`, `message.download`) são apagados 1 hora depois (410 `result_expired`), e o telefone que só o número conhece vem oculto sem o escopo `audiences:export`. A coleta de um público é interna e não aparece aqui.\n\n**Envelope (`?envelope=1`).** Sempre 200, com o estado dentro: `{\"data\": {\"id\", \"kind\", \"state\", \"result\", \"error\", \"created_at\", \"updated_at\", \"expires_at\"}}`. `state`: `queued`/`running` (ainda roda; `Retry-After: 1`), `succeeded` (`result` preenchido, ou `null` com `error.code` `result_expired`), `failed` (`error.code` do WhatsApp, `retryable: false`), `unknown` (`outcome_unknown` ou o código do motor, `retryable: false`: confira antes de repetir), `expired` (`engine_timeout`, `retryable: true`: nada foi feito). Sem o parâmetro, a resposta não muda.\n\nEscopo: `engine:read`; com só `calls:read` ou `calls:write`, apenas operações de ligação (as demais respondem 404).",
        "tags": [
          "Áreas de trabalho e operações"
        ],
        "x-scopes": [
          "engine:read",
          "calls:read",
          "calls:write"
        ],
        "parameters": [
          {
            "name": "envelope",
            "in": "query",
            "required": false,
            "description": "`1` responde sempre 200 com o estado dentro de `data` (ver acima).",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída (`data` traz o resultado) ou, com `?envelope=1`, qualquer estado.",
            "headers": {
              "Retry-After": {
                "description": "Com `?envelope=1` e `state` `queued` ou `running`: segundos até perguntar de novo (1).",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "type": "object",
                      "required": [
                        "data"
                      ],
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/EngineResult"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "required": [
                        "data"
                      ],
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/OperationEnvelope"
                        }
                      },
                      "additionalProperties": false
                    }
                  ]
                },
                "examples": {
                  "resultado": {
                    "summary": "Sem envelope (operação concluída)",
                    "value": {
                      "data": {
                        "jid": "120363025246125888@g.us",
                        "subject": "Clientes"
                      }
                    }
                  },
                  "envelope-rodando": {
                    "summary": "?envelope=1, ainda rodando",
                    "value": {
                      "data": {
                        "id": "5e4d3c2b-1a0f-4e9d-8c7b-6a5f4e3d2c1b",
                        "kind": "group.info",
                        "state": "running",
                        "result": null,
                        "error": null,
                        "created_at": "2026-10-30T12:00:00.000Z",
                        "updated_at": "2026-10-30T12:00:01.000Z",
                        "expires_at": "2026-10-30T12:01:00.000Z"
                      }
                    }
                  },
                  "envelope-incerto": {
                    "summary": "?envelope=1, resultado incerto",
                    "value": {
                      "data": {
                        "id": "5e4d3c2b-1a0f-4e9d-8c7b-6a5f4e3d2c1b",
                        "kind": "group.participants.update",
                        "state": "unknown",
                        "result": null,
                        "error": {
                          "code": "outcome_unknown",
                          "retryable": false
                        },
                        "created_at": "2026-10-30T12:00:00.000Z",
                        "updated_at": "2026-10-30T12:01:05.000Z",
                        "expires_at": "2026-10-30T12:01:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "410": {
            "$ref": "#/components/responses/Error",
            "description": "`result_expired`: o resultado tinha dados pessoais e já foi apagado; refaça a consulta."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed"
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/account": {
      "get": {
        "summary": "Ver plano, limites e uso da conta",
        "operationId": "get-v1-account",
        "description": "O plano em vigor da organização da chave, de onde ele vem (`source`: `subscription` assinatura, `license` licença, `courtesy` cortesia, `none` sem plano), os limites, os recursos do plano (`features`: `api`, `mcp`) e o uso atual. Cortesia e conta sem plano não têm `plan.code`: a cortesia usa os limites do Growth; sem plano, os do Start. Um limite `null` significa que o catálogo não tem versão do plano para lê-lo. `webhook_endpoints` vale por área de trabalho; `webhook_endpoints_used` soma a organização. `requests_this_minute` já conta este pedido.\n\nEscopo: `account:read` (chaves criadas antes dele: `workspaces:read`).",
        "tags": [
          "Áreas de trabalho e operações"
        ],
        "x-scopes": [
          "account:read"
        ],
        "responses": {
          "200": {
            "description": "Plano, limites, recursos e uso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "organization_id",
                        "plan",
                        "limits",
                        "features",
                        "usage"
                      ],
                      "properties": {
                        "organization_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "plan": {
                          "type": "object",
                          "required": [
                            "code",
                            "source"
                          ],
                          "properties": {
                            "code": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "Plano (`start`, `growth`, `agency`…); `null` em cortesia e sem plano."
                            },
                            "source": {
                              "type": "string",
                              "enum": [
                                "subscription",
                                "license",
                                "courtesy",
                                "none"
                              ]
                            }
                          }
                        },
                        "limits": {
                          "type": "object",
                          "properties": {
                            "number_slots": {
                              "type": "integer",
                              "description": "Números que a conta pode ter, já com números extras em vigor."
                            },
                            "workspace_limit": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "member_limit": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "description": "Pessoas da equipe, contando convites pendentes."
                            },
                            "api_rate_per_minute": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "description": "Pedidos por minuto, somando todas as chaves da organização."
                            },
                            "pending_messages": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "description": "Envios aguardando na fila de cada número."
                            },
                            "webhook_endpoints": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "description": "Webhooks ativos por área de trabalho."
                            },
                            "call_quantity": {
                              "type": "integer",
                              "description": "Números com ligações contratadas."
                            }
                          }
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "api",
                              "mcp"
                            ]
                          }
                        },
                        "usage": {
                          "type": "object",
                          "properties": {
                            "requests_this_minute": {
                              "type": "integer"
                            },
                            "numbers_used": {
                              "type": "integer"
                            },
                            "webhook_endpoints_used": {
                              "type": "integer"
                            },
                            "members": {
                              "type": "integer"
                            },
                            "workspaces": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          }
        }
      }
    },
    "/v1/account/export": {
      "get": {
        "summary": "Baixar os dados da conta",
        "operationId": "get-v1-account-export",
        "description": "O mesmo arquivo de \"Baixar meus dados\" do console: um JSON com a conta, a equipe, os números, contatos e CRM, etiquetas, respostas rápidas e todas as mensagens guardadas, já abertas. É gerado na hora e enviado aos poucos (nunca fica guardado); o arquivo completo termina com `\"completo\": true` — sem isso, a transferência foi interrompida e vale baixar de novo.\n\nSó para uma chave da organização inteira (presa a área de trabalho ou número: 403 `scope_denied`) criada por quem é **dona da conta** agora (senão 403 `owner_required`). Conta nas 3 vezes por hora dessa pessoa, somando console e API (429 `rate_limited`), e fica registrado no histórico da equipe com a chave usada. Conta suspensa baixa pelo console.\n\nEscopo: `account:read` (o `workspaces:read` aceito em `GET /v1/account` não vale aqui).",
        "tags": [
          "Áreas de trabalho e operações"
        ],
        "x-scopes": [
          "account:read"
        ],
        "responses": {
          "200": {
            "description": "O arquivo, `Content-Disposition: attachment; filename=\"flowzap-dados-AAAA-MM-DD.json\"`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "formato",
                    "completo"
                  ],
                  "properties": {
                    "formato": {
                      "type": "string",
                      "enum": [
                        "flowzap-dados-v1"
                      ]
                    },
                    "completo": {
                      "type": "boolean"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `owner_required`, `organization_suspended`"
          },
          "429": {
            "$ref": "#/components/responses/Error",
            "description": "`rate_limited`: mais de 3 downloads na última hora pela mesma pessoa, ou acima dos pedidos por minuto do plano."
          }
        }
      }
    },
    "/v1/team/members": {
      "get": {
        "summary": "Listar pessoas da equipe",
        "operationId": "get-v1-team-members",
        "description": "As pessoas da organização que quem criou a chave administra, como na tela Equipe do console: dono vê todas; administrador vê as que pode gerenciar. Uma pessoa com acesso a mais de uma área de trabalho aparece uma vez por acesso. Uma chave presa a uma área de trabalho vê só os acessos daquela área.\n\n**A chave age por quem a criou**, com o papel atual dessa pessoa. Chave sem criador (anterior ao registro de criador) ou cuja pessoa não é mais dona nem administradora: 403 `team_manager_required`. Chave presa a um número não administra a equipe (403 `scope_denied`).\n\nEscopo: `team:read`.",
        "tags": [
          "Equipe"
        ],
        "x-scopes": [
          "team:read"
        ],
        "responses": {
          "200": {
            "description": "Acessos da equipe, até 200.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TeamMember"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`: falta `team:read` ou a chave está presa a um número. `team_manager_required`: quem criou a chave não é dono nem administrador. `organization_suspended`: conta suspensa ou encerrada."
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          }
        }
      }
    },
    "/v1/team/members/{membershipId}": {
      "parameters": [
        {
          "name": "membershipId",
          "in": "path",
          "required": true,
          "description": "`id` do acesso, de `GET /v1/team/members`.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "delete": {
        "summary": "Remover uma pessoa da equipe",
        "operationId": "delete-v1-team-members-membershipId",
        "description": "Remove um acesso e encerra as sessões do console dessa pessoa, com as mesmas regras do console: o dono nunca é removido; administrador remove só desenvolvedor, operador e leitura; ninguém remove a si mesmo (a pessoa que criou a chave). No histórico da equipe, quem removeu é a pessoa que criou a chave, com a indicação da chave usada.\n\n`Idempotency-Key` opcional: repetir com a mesma chave depois de remover responde 204 com `Idempotent-Replay: true`; sem ela, a repetição responde 404.\n\nEscopo: `team:write`.",
        "tags": [
          "Equipe"
        ],
        "x-scopes": [
          "team:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "204": {
            "description": "Removido (ou repetição de um pedido já atendido, com `Idempotent-Replay: true`)."
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`: falta `team:write`, a chave está presa a um número, ou o papel de quem criou a chave não permite remover esse acesso (o do dono, por exemplo). `self_removal_denied`: é o acesso de quem criou a chave. `team_manager_required`: quem criou a chave não é dono nem administrador."
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          }
        }
      }
    },
    "/v1/team/invitations": {
      "get": {
        "summary": "Listar convites da equipe",
        "operationId": "get-v1-team-invitations",
        "description": "Os 100 convites mais recentes que quem criou a chave administra, com a situação (`pending`, `accepted`, `revoked`, `expired`). Uma chave presa a uma área de trabalho vê só os convites daquela área.\n\nEscopo: `team:read`.",
        "tags": [
          "Equipe"
        ],
        "x-scopes": [
          "team:read"
        ],
        "responses": {
          "200": {
            "description": "Convites, do mais recente ao mais antigo.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TeamInvitation"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `team_manager_required` ou `organization_suspended` (ver `GET /v1/team/members`)."
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          }
        }
      },
      "post": {
        "summary": "Convidar uma pessoa",
        "operationId": "post-v1-team-invitations",
        "description": "Envia o convite por e-mail (link válido por 7 dias), como a tela Equipe do console, sem pedir senha: a chave é a credencial. O papel vai no máximo até `admin`, e só se quem criou a chave for o dono; administrador convida só `developer`, `operator` e `viewer`. `owner` nunca: a transferência de propriedade fica só no console. `workspace_id: null` dá acesso à organização inteira; uma chave presa a uma área de trabalho só convida para ela (outra área ou `null`: 404).\n\nAs pessoas da equipe seguem o plano (pessoas da organização + convites pendentes válidos; convidar quem já conta não soma): acima do limite, 409 `member_limit_reached`. Até 20 convites a cada 15 minutos por chave.\n\nExige `Idempotency-Key`: repetir o mesmo pedido devolve o mesmo convite (200, `Idempotent-Replay: true`) sem mandar outro e-mail; com outro conteúdo, 409 `idempotency_conflict`.\n\nEscopo: `team:write`.",
        "tags": [
          "Equipe"
        ],
        "x-scopes": [
          "team:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "email",
                  "role",
                  "workspace_id"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 254,
                    "description": "Guardado em minúsculas."
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "admin",
                      "developer",
                      "operator",
                      "billing",
                      "viewer"
                    ]
                  },
                  "workspace_id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Repetição de um pedido já atendido (`Idempotent-Replay: true`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamInvitationCreated"
                }
              }
            }
          },
          "201": {
            "description": "Convite criado; o e-mail sai pela fila de envio.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamInvitationCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `idempotency_key_required`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`: falta `team:write`, a chave está presa a um número, ou o papel de quem criou a chave não permite convidar com esse papel. `team_manager_required`, `organization_suspended`."
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`member_limit_reached`: o plano não comporta mais pessoas. `idempotency_conflict`: a mesma `Idempotency-Key` com outro conteúdo."
          },
          "429": {
            "$ref": "#/components/responses/Error",
            "description": "`rate_limited`: mais de 20 convites em 15 minutos com esta chave, ou a organização passou dos pedidos por minuto do plano (com `Retry-After`)."
          }
        }
      }
    },
    "/v1/team/invitations/{invitationId}": {
      "parameters": [
        {
          "name": "invitationId",
          "in": "path",
          "required": true,
          "description": "`id` do convite.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "delete": {
        "summary": "Cancelar um convite",
        "operationId": "delete-v1-team-invitations-invitationId",
        "description": "Cancela um convite pendente; o link do e-mail deixa de valer. Mesmas regras de papel do convite.\n\n`Idempotency-Key` opcional: repetir com a mesma chave depois de cancelar responde 204 com `Idempotent-Replay: true`; sem ela, a repetição responde 409 `invitation_closed`.\n\nEscopo: `team:write`.",
        "tags": [
          "Equipe"
        ],
        "x-scopes": [
          "team:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "204": {
            "description": "Cancelado (ou repetição de um pedido já atendido, com `Idempotent-Replay: true`)."
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `team_manager_required` ou `organization_suspended`."
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`invitation_closed`: o convite já foi aceito ou cancelado."
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          }
        }
      }
    },
    "/v1/billing/subscription": {
      "get": {
        "summary": "Ver assinatura, faturas e pagamentos pendentes",
        "operationId": "get-v1-billing-subscription",
        "description": "O que a tela Assinatura do console mostra, numa resposta só: o plano em vigor e de onde vem (`plan`), a situação comercial (`commercial`: `state` e `until`), a assinatura (`subscription`: situação, fim do período pago, `cancel_at_period_end`, forma de pagamento, `last_invoice_url` da última fatura do cartão e `next_charge_date`), a **fatura de renovação em aberto** (`renewal_cycle`: período, `amount_minor` em centavos e `link` do Pix enquanto vale), o **checkout ainda aberto** da primeira contratação (`checkout`: `state`, `attempt_state`, `link`, valor), as ligações (`calls`), as Gravações no FlowZap (`recordings`) e os avisos: mudança de plano agendada (`plan_change`, com o `id` para confirmar), desconto, prorrogação e números extras que vencem. Ausente: `null`.\n\nNão há histórico de pagamentos antigos nesta versão (o console também não mostra): a fatura aberta e o link da última fatura do cartão estão acima. Valores em centavos.\n\n**Cobrança é da conta inteira**: a chave não pode estar presa a uma área de trabalho ou número, e age por quem a criou, que precisa ser dono ou responsável pela cobrança da conta (como no console).\n\nEscopo: `billing:read`.",
        "tags": [
          "Cobrança"
        ],
        "x-scopes": [
          "billing:read"
        ],
        "responses": {
          "200": {
            "description": "Resumo da cobrança.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "plan",
                        "commercial",
                        "subscription",
                        "renewal_cycle",
                        "checkout",
                        "calls"
                      ],
                      "properties": {
                        "plan": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "source": {
                              "type": "string",
                              "enum": [
                                "subscription",
                                "license",
                                "courtesy",
                                "none"
                              ]
                            }
                          }
                        },
                        "commercial": {
                          "type": "object",
                          "properties": {
                            "state": {
                              "type": "string",
                              "description": "`paid`, `license`, `courtesy`, `lapsed`, `no_plan`…"
                            },
                            "until": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            }
                          }
                        },
                        "subscription": {
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "renewal_cycle": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "description": "Fatura de renovação em aberto, com o link do Pix enquanto vale (2 horas)."
                        },
                        "checkout": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "description": "Checkout da primeira contratação."
                        },
                        "card_charges_closing": {
                          "type": "boolean"
                        },
                        "calls": {
                          "$ref": "#/components/schemas/CallsAddon"
                        },
                        "recordings": {
                          "$ref": "#/components/schemas/RecordingsAddon"
                        },
                        "plan_change": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "description": "Mudança de plano agendada: `id`, `target_plan`, `effective_on`, `requires_confirmation`, `confirmed`, `monthly_from_minor`, `monthly_to_minor`."
                        },
                        "discount": {
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "extension": {
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "extra_numbers_ending": {
                          "type": [
                            "object",
                            "null"
                          ]
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "environment": {
                          "type": "string",
                          "enum": [
                            "sandbox",
                            "production"
                          ]
                        },
                        "checkout_hosts": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Endereços aceitos para os links de pagamento."
                        },
                        "card_enabled": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/BillingForbidden"
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`billing_read_unavailable`: cobrança indisponível agora."
          }
        }
      }
    },
    "/v1/billing/offers": {
      "get": {
        "summary": "Listar ofertas de planos",
        "operationId": "get-v1-billing-offers",
        "description": "As ofertas à venda e as propostas liberadas pela equipe FlowZap para esta conta. Use o `id` da oferta como `price_id` no checkout.\n\nEscopo: `billing:read`.",
        "tags": [
          "Cobrança"
        ],
        "x-scopes": [
          "billing:read"
        ],
        "responses": {
          "200": {
            "description": "Ofertas (`data`) e `meta` (`environment`, `checkout_hosts`, `card_enabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/BillingForbidden"
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`checkout_unavailable`: a venda está desligada agora."
          }
        }
      }
    },
    "/v1/billing/renewal-attention": {
      "get": {
        "summary": "Ver pendências da renovação",
        "operationId": "get-v1-billing-renewal-attention",
        "description": "O que pede atenção na renovação e no pagamento dela (atraso, Pix vencido, conferência com o Asaas atrasada), como o aviso do console.\n\nEscopo: `billing:read`.",
        "tags": [
          "Cobrança"
        ],
        "x-scopes": [
          "billing:read"
        ],
        "responses": {
          "200": {
            "description": "Pendências (`data`); `as_of` é o momento da leitura.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": [
                        "object",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/BillingForbidden"
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`billing_read_unavailable`."
          }
        }
      }
    },
    "/v1/billing/addons/calls": {
      "get": {
        "summary": "Ver ligações contratadas",
        "operationId": "get-v1-billing-addons-calls",
        "description": "Em quantos números a conta tem ligações, o máximo do plano, o preço por número, a redução agendada e o aumento ainda por pagar.\n\nEscopo: `billing:read`.",
        "tags": [
          "Cobrança"
        ],
        "x-scopes": [
          "billing:read"
        ],
        "responses": {
          "200": {
            "description": "Ligações da conta.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CallsAddon"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/BillingForbidden"
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`billing_unavailable`."
          }
        }
      },
      "post": {
        "summary": "Mudar a quantidade de números com ligações",
        "operationId": "post-v1-billing-addons-calls",
        "description": "Corpo: `{\"quantity\": N, \"method\": \"pix\" | \"credit_card\"}`. **Aumento**: cobra agora o proporcional dos dias que faltam no período (mínimo R$ 5,00), por Pix ou cartão (`method` obrigatório), num checkout avulso do Asaas; responde 201 com o `link` e a quantidade sobe depois do pagamento confirmado. **Redução**: agendada para a próxima renovação, sem reembolso (200, `result: scheduled`). A quantidade atual de novo cancela a redução agendada (200, `result: unchanged`).\n\n`Idempotency-Key` obrigatória (16 a 128 caracteres): repetir com a mesma chave devolve o mesmo resultado e o mesmo link, sem novo checkout; com outra quantidade ou forma, 409 `idempotency_conflict`.\n\nEscopo: `billing:write`.",
        "tags": [
          "Cobrança"
        ],
        "x-scopes": [
          "billing:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "responses": {
          "200": {
            "description": "`result: scheduled` (redução agendada) ou `unchanged`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "$ref": "#/components/responses/CheckoutLink"
          },
          "202": {
            "$ref": "#/components/responses/CheckoutPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_key_required`, `invalid_idempotency_key`, `invalid_input` (aumento sem `method`, chave com menos de 16 caracteres)."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/BillingForbidden"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`; `addon_change_refused` com `error.reason` (`no_active_subscription`, `cancel_scheduled`, `quantity_above_slots`, `renewal_already_prepared`, `addon_change_open`, `card_charge_too_close`, `card_next_charge_paid`)."
          },
          "410": {
            "$ref": "#/components/responses/Error",
            "description": "`checkout_expired`: venceu sem pagamento ou o plano mudou; peça de novo com outra chave."
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`checkout_rejected`: o Asaas recusou criar o checkout."
          },
          "429": {
            "$ref": "#/components/responses/CheckoutRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/CheckoutUnavailable"
          }
        }
      }
    },
    "/v1/billing/addons/recordings": {
      "get": {
        "summary": "Ver Gravações no FlowZap contratadas",
        "operationId": "get-v1-billing-addons-recordings",
        "description": "O módulo Gravações no FlowZap (R$ 29 por número/mês): ouvir e baixar as gravações das ligações no console e guardá-las até 90 dias, com até 10 GB por conta. Sem o módulo, a gravação fica disponível 7 dias só pela API. Mostra em quantos números a conta tem o módulo, o máximo do plano, o preço por número, a redução agendada e o aumento ainda por pagar.\n\nEscopo: `billing:read`.",
        "tags": [
          "Cobrança"
        ],
        "x-scopes": [
          "billing:read"
        ],
        "responses": {
          "200": {
            "description": "Gravações no FlowZap da conta.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RecordingsAddon"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/BillingForbidden"
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`billing_unavailable`."
          }
        }
      },
      "post": {
        "summary": "Mudar a quantidade de números com Gravações no FlowZap",
        "operationId": "post-v1-billing-addons-recordings",
        "description": "Igual a `POST /v1/billing/addons/calls`, para o módulo Gravações no FlowZap. Corpo: `{\"quantity\": N, \"method\": \"pix\" | \"credit_card\"}`. **Aumento**: cobra agora o proporcional dos dias que faltam no período (mínimo R$ 5,00), por Pix ou cartão (`method` obrigatório), num checkout avulso do Asaas; responde 201 com o `link` e a quantidade sobe depois do pagamento confirmado. **Redução**: agendada para a próxima renovação, sem reembolso (200, `result: scheduled`). A quantidade atual de novo cancela a redução agendada (200, `result: unchanged`). Depois de contratar, escolha no console quais números usam o módulo.\n\n`Idempotency-Key` obrigatória (16 a 128 caracteres): repetir com a mesma chave devolve o mesmo resultado e o mesmo link, sem novo checkout; com outra quantidade, forma ou com a chave usada nas ligações, 409 `idempotency_conflict`.\n\nEscopo: `billing:write`.",
        "tags": [
          "Cobrança"
        ],
        "x-scopes": [
          "billing:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "responses": {
          "200": {
            "description": "`result: scheduled` (redução agendada) ou `unchanged`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "$ref": "#/components/responses/CheckoutLink"
          },
          "202": {
            "$ref": "#/components/responses/CheckoutPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_key_required`, `invalid_idempotency_key`, `invalid_input` (aumento sem `method`, chave com menos de 16 caracteres)."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/BillingForbidden"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`; `addon_change_refused` com `error.reason` (`no_active_subscription`, `cancel_scheduled`, `quantity_above_slots`, `renewal_already_prepared`, `addon_change_open`, `card_charge_too_close`, `card_next_charge_paid`)."
          },
          "410": {
            "$ref": "#/components/responses/Error",
            "description": "`checkout_expired`: venceu sem pagamento ou o plano mudou; peça de novo com outra chave."
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`checkout_rejected`: o Asaas recusou criar o checkout."
          },
          "429": {
            "$ref": "#/components/responses/CheckoutRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/CheckoutUnavailable"
          }
        }
      }
    },
    "/v1/billing/checkout/pix": {
      "post": {
        "summary": "Contratar um plano por Pix",
        "operationId": "post-v1-billing-checkout-pix",
        "description": "A primeira contratação da conta. Corpo: `{\"price_id\": \"<id da oferta>\", \"call_quantity\": 0}` — `call_quantity` são os números com ligações (0 até os números do plano), cobrados junto com o plano. Responde 201 com o `link` do checkout do Asaas; a assinatura começa quando o Pix é pago. Um plano por conta: mudar de plano passa pela equipe FlowZap.\n\n`Idempotency-Key` obrigatória (16 a 128 caracteres): a mesma chave devolve o mesmo checkout e nunca cria outro no Asaas; com outra oferta, 409 `idempotency_conflict`. Checkout vencido sem pagamento (2 horas): 410, peça de novo com outra chave.\n\nEscopo: `billing:write`.",
        "tags": [
          "Cobrança"
        ],
        "x-scopes": [
          "billing:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "responses": {
          "201": {
            "$ref": "#/components/responses/CheckoutLink"
          },
          "202": {
            "$ref": "#/components/responses/CheckoutPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_key_required`, `invalid_idempotency_key`, `invalid_input`, `invalid_call_quantity` (mais números com ligações que o plano)."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/BillingForbidden"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`subscription_exists`, `checkout_open` (outro checkout ainda pode ser pago), `idempotency_conflict`."
          },
          "410": {
            "$ref": "#/components/responses/Error",
            "description": "`checkout_expired`."
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`checkout_rejected`."
          },
          "429": {
            "$ref": "#/components/responses/CheckoutRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/CheckoutUnavailable"
          }
        }
      }
    },
    "/v1/billing/checkout/card": {
      "post": {
        "summary": "Contratar um plano com cartão de crédito",
        "operationId": "post-v1-billing-checkout-card",
        "description": "Igual ao Pix, com a assinatura recorrente no cartão: **o cartão é digitado na página do Asaas** (`link`), nunca enviado ao FlowZap. Só planos mensais e sem cupom. Disponível quando `meta.card_enabled` é true; senão 503 `card_checkout_unavailable`.\n\n`Idempotency-Key` obrigatória (16 a 128 caracteres).\n\nEscopo: `billing:write`.",
        "tags": [
          "Cobrança"
        ],
        "x-scopes": [
          "billing:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "responses": {
          "201": {
            "$ref": "#/components/responses/CheckoutLink"
          },
          "202": {
            "$ref": "#/components/responses/CheckoutPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_key_required`, `invalid_idempotency_key`, `invalid_input`, `invalid_call_quantity`."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/BillingForbidden"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`subscription_exists`, `checkout_open`, `idempotency_conflict`, `card_unavailable` com `error.reason` (`card_monthly_only`, `card_discount_unavailable`, `card_subscription_live`, `card_duplicate_subscription`)."
          },
          "410": {
            "$ref": "#/components/responses/Error",
            "description": "`checkout_expired`."
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`checkout_rejected`."
          },
          "429": {
            "$ref": "#/components/responses/CheckoutRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/CheckoutUnavailable"
          }
        }
      }
    },
    "/v1/billing/renewal-cycles/{cycleId}/checkout/pix": {
      "parameters": [
        {
          "name": "cycleId",
          "in": "path",
          "required": true,
          "description": "`renewal_cycle.id` de `GET /v1/billing/subscription`.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Pagar a renovação por Pix",
        "operationId": "post-v1-billing-renewal-cycles-cycleId-checkout-pix",
        "description": "Cria (ou devolve) o Pix da fatura de renovação em aberto. Idempotente pela fatura: pedir de novo devolve o mesmo link enquanto vale; depois de vencido (2 horas), 410 e o próximo pedido cria outro. Sem corpo; `Idempotency-Key` não é necessária.\n\nEscopo: `billing:write`.",
        "tags": [
          "Cobrança"
        ],
        "x-scopes": [
          "billing:write"
        ],
        "responses": {
          "201": {
            "$ref": "#/components/responses/CheckoutLink"
          },
          "202": {
            "$ref": "#/components/responses/CheckoutPending"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/BillingForbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`renewal_checkout_unavailable`: a fatura não está aberta (paga, de outra conta, ou o cartão cobra esta renovação)."
          },
          "410": {
            "$ref": "#/components/responses/Error",
            "description": "`checkout_expired`: o Pix anterior venceu; peça de novo."
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`checkout_rejected`."
          },
          "429": {
            "$ref": "#/components/responses/CheckoutRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/CheckoutUnavailable"
          }
        }
      }
    },
    "/v1/billing/subscription/renewal": {
      "post": {
        "summary": "Encerrar (ou manter) a assinatura no fim do período",
        "operationId": "post-v1-billing-subscription-renewal",
        "description": "Corpo: `{\"subscription_id\": \"<subscription.id>\", \"cancel_at_period_end\": true}`. `true` agenda o encerramento para o fim do período pago (nada é cobrado depois); `false` desfaz. Sem reembolso.\n\n`Idempotency-Key` obrigatória e **no formato UUID**: a mesma chave devolve o mesmo resultado; com outro conteúdo, 409 `renewal_conflict`.\n\nEscopo: `billing:write`.",
        "tags": [
          "Cobrança"
        ],
        "x-scopes": [
          "billing:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "responses": {
          "200": {
            "description": "`subscription_id`, `cancel_at_period_end`, `effective_at`, `state`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_key_required`, `invalid_idempotency_key`, `invalid_input` (chave que não é UUID, corpo inválido)."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/BillingForbidden"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`renewal_conflict`: chave repetida com outro conteúdo, ou a assinatura não tem período pago em aberto."
          },
          "429": {
            "$ref": "#/components/responses/CheckoutRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`renewal_unavailable`."
          }
        }
      }
    },
    "/v1/billing/plan-changes/{changeId}/confirm": {
      "parameters": [
        {
          "name": "changeId",
          "in": "path",
          "required": true,
          "description": "`plan_change.id` de `GET /v1/billing/subscription`.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Confirmar a mudança de plano agendada",
        "operationId": "post-v1-billing-plan-changes-changeId-confirm",
        "description": "Confirma a mudança de plano agendada pela equipe FlowZap que aumenta o valor (`plan_change.requires_confirmation`), antes de a renovação ser preparada. Idempotente: confirmar de novo responde 200 sem refazer. Sem corpo; `Idempotency-Key` não é necessária.\n\nEscopo: `billing:write`.",
        "tags": [
          "Cobrança"
        ],
        "x-scopes": [
          "billing:write"
        ],
        "responses": {
          "200": {
            "description": "`data.change`: a mudança confirmada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/BillingForbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`change_not_scheduled`, `confirmation_not_required`."
          }
        }
      }
    },
    "/v1/calls/numbers": {
      "get": {
        "summary": "Ver os números com ligações (beta)",
        "operationId": "get-v1-calls-numbers",
        "description": "**Beta.** A quantidade de números com ligações contratada (assinatura, licença ou cortesia), quantos estão escolhidos, se a conta tem a liberação de teste (`trial`, o piloto) e cada número com `selected` e `calls_enabled` (ligações ativas agora). Uma chave presa a uma área de trabalho ou a um número vê só os números dela; `quantity` e `selected` são da conta.\n\nUma chave da organização inteira vê a escolha da conta toda, como no console: só enquanto quem criou a chave é **dona ou administradora da conta inteira** (senão 403 `owner_or_admin_required`).\n\nEscopo: `calls:read` ou `calls:admin`.",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:read",
          "calls:admin"
        ],
        "responses": {
          "200": {
            "description": "Quantidade contratada e números.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "quantity",
                        "selected",
                        "trial",
                        "numbers"
                      ],
                      "properties": {
                        "quantity": {
                          "type": "integer"
                        },
                        "selected": {
                          "type": "integer"
                        },
                        "trial": {
                          "type": "boolean"
                        },
                        "numbers": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "instance_id",
                              "workspace_id",
                              "name",
                              "selected",
                              "selected_at",
                              "calls_enabled"
                            ],
                            "properties": {
                              "instance_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "workspace_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": "string"
                              },
                              "selected": {
                                "type": "boolean"
                              },
                              "selected_at": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "date-time"
                              },
                              "calls_enabled": {
                                "type": "boolean"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `owner_or_admin_required`, `organization_suspended`"
          }
        }
      },
      "put": {
        "summary": "Escolher os números com ligações (beta)",
        "operationId": "put-v1-calls-numbers",
        "description": "**Beta.** Os números com ligações passam a ser exatamente `instance_ids` (até a quantidade contratada; acima, 409 `call_quantity_exceeded` com `quantity` e `requested`). Cada número que mudou reconecta para aplicar (`changes[].reconnect`: `now`, `later` com `retry_after_s` — reconectou há menos de 10 minutos — ou `not_connected`, aplicado quando o número voltar); desligar vale na hora. Acompanhe a conclusão por `GET /v1/calls/numbers` (`calls_enabled`) ou por `GET …/calls/readiness` do número. Enviar a mesma lista de novo não muda nada nem reconecta: a rota é idempotente por si (`Idempotency-Key` é aceita, não necessária). Fica registrado como feito por quem criou a chave.\n\nSó chaves da organização inteira: chave presa a uma área de trabalho ou a um número recebe 403 `organization_key_required`. Quem criou a chave precisa ser, agora, **dona ou administradora da conta inteira**, como no console (senão 403 `owner_or_admin_required`).\n\nEscopo: `calls:write` ou `calls:admin`.",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:write",
          "calls:admin"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "instance_ids"
                ],
                "properties": {
                  "instance_ids": {
                    "type": "array",
                    "maxItems": 100,
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Como o GET, com `changes`: `[{instance_id, selected, reconnect, retry_after_s?}]`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "quantity",
                        "selected",
                        "trial",
                        "numbers",
                        "changes"
                      ],
                      "properties": {
                        "quantity": {
                          "type": "integer"
                        },
                        "selected": {
                          "type": "integer"
                        },
                        "trial": {
                          "type": "boolean"
                        },
                        "numbers": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "changes": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "instance_id",
                              "selected",
                              "reconnect"
                            ],
                            "properties": {
                              "instance_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "selected": {
                                "type": "boolean"
                              },
                              "reconnect": {
                                "type": "string",
                                "enum": [
                                  "now",
                                  "later",
                                  "not_connected"
                                ]
                              },
                              "retry_after_s": {
                                "type": "integer"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `organization_key_required` (chave presa a área de trabalho ou número), `owner_or_admin_required`, `organization_suspended`"
          },
          "404": {
            "$ref": "#/components/responses/Error",
            "description": "`number_not_found` (número fora da conta)"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`call_quantity_exceeded` (com `quantity` e `requested`)"
          }
        }
      }
    },
    "/v1/calls/media-origins": {
      "get": {
        "summary": "Ver as origens do áudio no navegador (beta)",
        "operationId": "get-v1-calls-media-origins",
        "description": "**Beta.** Os endereços de sistema (origens exatas, `https://host[:porta]`) que podem abrir o áudio das ligações desta conta pelo navegador, até 10. Valem para a conta inteira (todos os números) e só para ela: cada conta, homologação ou produção, tem a própria lista.\n\nSem nenhuma origem, o áudio abre no domínio do FlowZap e em clientes fora do navegador (servidor, app nativo), que não enviam origem. Com origens cadastradas, o bilhete de áudio emitido pela API (`POST …/calls` com `audio`, `…/answer`, `…/media-ticket`) passa a levá-las assinadas, e o WebSocket recusa um navegador de outra origem. Nada é guardado na URL do navegador além do bilhete de 60 s.\n\nSó chaves da organização inteira (chave presa a área de trabalho ou número: 403 `organization_key_required`), criadas por quem é, agora, **dona ou administradora da conta inteira** (senão 403 `owner_or_admin_required`).\n\nEscopo: `calls:read` ou `calls:admin`.",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:read",
          "calls:admin"
        ],
        "responses": {
          "200": {
            "description": "O limite e as origens, da mais antiga para a mais nova.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "limit",
                        "origins"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "const": 10
                        },
                        "origins": {
                          "type": "array",
                          "maxItems": 10,
                          "items": {
                            "type": "object",
                            "required": [
                              "origin",
                              "created_at"
                            ],
                            "properties": {
                              "origin": {
                                "type": "string",
                                "description": "Forma canônica: minúsculas, sem barra final, sem a porta padrão."
                              },
                              "created_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "limit": 10,
                    "origins": [
                      {
                        "origin": "https://homologacao.exemplo.com.br",
                        "created_at": "2026-11-03T13:10:00.000Z"
                      },
                      {
                        "origin": "https://app.exemplo.com.br",
                        "created_at": "2026-11-03T13:12:00.000Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `organization_key_required`, `owner_or_admin_required`, `organization_suspended`"
          }
        }
      },
      "post": {
        "summary": "Cadastrar uma origem do áudio no navegador (beta)",
        "operationId": "post-v1-calls-media-origins",
        "description": "**Beta.** Libera uma origem exata para o áudio das ligações da conta. Aceita `https://host` ou `https://host:porta`; para desenvolvimento, também `http://localhost[:porta]` e `http://127.0.0.1[:porta]`. Recusa (400 `invalid_origin`) caminho, `?`, `#`, usuário e senha, `*` e qualquer outro `http://`. A origem é guardada na forma canônica (minúsculas, sem barra final, sem `:443`), com até 120 caracteres.\n\nIdempotente por si: cadastrar uma origem que já está na lista responde 200 com a mesma lista, sem registrar nada; uma nova responde 201. A 11ª recebe 409 `media_origins_limit` (remova uma antes). Vale para os bilhetes emitidos depois; um bilhete já emitido continua com as origens que tinha. Cada inclusão fica registrada (quem criou a chave, qual chave, quando).\n\nEscopo: `calls:admin`.",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:admin"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "origin"
                ],
                "properties": {
                  "origin": {
                    "type": "string",
                    "maxLength": 300
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "origin": "https://app.exemplo.com.br"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A origem já estava na lista: nada mudou. Mesmo corpo do GET.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "limit",
                        "origins"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "origins": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Origem cadastrada. Mesmo corpo do GET, já com ela.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "limit",
                        "origins"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "origins": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "limit": 10,
                    "origins": [
                      {
                        "origin": "https://app.exemplo.com.br",
                        "created_at": "2026-11-03T13:12:00.000Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input` (corpo), `invalid_origin` (não é uma origem exata aceita)"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `organization_key_required`, `owner_or_admin_required`, `organization_suspended`"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`media_origins_limit`: a conta já tem 10 origens."
          }
        }
      },
      "delete": {
        "summary": "Remover uma origem do áudio no navegador (beta)",
        "operationId": "delete-v1-calls-media-origins",
        "description": "**Beta.** Remove a origem informada em `origin` (qualquer grafia da mesma origem serve). Idempotente: remover uma origem que não está na lista responde 200 com `removed: false`. Os bilhetes emitidos depois deixam de aceitá-la; um bilhete já emitido vale até vencer (60 s para conectar). Cada remoção fica registrada (quem criou a chave, qual chave, quando).\n\nEscopo: `calls:admin`.",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:admin"
        ],
        "parameters": [
          {
            "name": "origin",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 300
            },
            "example": "https://homologacao.exemplo.com.br"
          }
        ],
        "responses": {
          "200": {
            "description": "`removed` diz se a origem estava na lista; `limit` e `origins` como no GET, já sem ela.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "removed",
                        "limit",
                        "origins"
                      ],
                      "properties": {
                        "removed": {
                          "type": "boolean"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "origins": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "removed": true,
                    "limit": 10,
                    "origins": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input` (sem `origin`), `invalid_origin`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `organization_key_required`, `owner_or_admin_required`, `organization_suspended`"
          }
        }
      }
    },
    "/v1/calls/test-numbers": {
      "get": {
        "summary": "Ver os números de teste do piloto (beta)",
        "operationId": "get-v1-calls-test-numbers",
        "description": "**Beta.** No piloto (`trial: true`, liberação de teste ligada pela equipe FlowZap), só os números de teste tocam no FlowZap quando ligam e só eles podem receber ligações; até 20. Um número com ligações contratadas (`PUT /v1/calls/numbers`) não tem essa restrição: liga e recebe de qualquer telefone. `added_at` é a última inclusão pela API (`null`: cadastrado antes pela equipe FlowZap). A lista aparece mesmo com o piloto desligado, mas só vale com ele ligado.\n\nSair do piloto é contratar ligações (`POST /v1/billing/addons/calls`) e escolher os números; ligar ou desligar o piloto continua com a equipe FlowZap.\n\nSó chaves da organização inteira (403 `organization_key_required`), de quem é, agora, **dona ou administradora da conta inteira** (403 `owner_or_admin_required`).\n\nEscopo: `calls:read` ou `calls:admin`.",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:read",
          "calls:admin"
        ],
        "responses": {
          "200": {
            "description": "Se o piloto está ligado, o limite e os números.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "trial",
                        "limit",
                        "numbers"
                      ],
                      "properties": {
                        "trial": {
                          "type": "boolean"
                        },
                        "limit": {
                          "type": "integer",
                          "const": 20
                        },
                        "numbers": {
                          "type": "array",
                          "maxItems": 20,
                          "items": {
                            "type": "object",
                            "required": [
                              "phone",
                              "added_at"
                            ],
                            "properties": {
                              "phone": {
                                "type": "string",
                                "description": "E.164."
                              },
                              "added_at": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "date-time"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "trial": true,
                    "limit": 20,
                    "numbers": [
                      {
                        "phone": "+5511900000001",
                        "added_at": "2026-11-03T13:20:00.000Z"
                      },
                      {
                        "phone": "+5541900000002",
                        "added_at": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `organization_key_required`, `owner_or_admin_required`, `organization_suspended`"
          }
        }
      },
      "put": {
        "summary": "Definir os números de teste do piloto (beta)",
        "operationId": "put-v1-calls-test-numbers",
        "description": "**Beta.** Os números de teste passam a ser exatamente `phones` (E.164; repetidos contam uma vez). Só com o piloto ligado (senão 409 `call_trial_not_enabled`; esta rota nunca liga o piloto); até 20 números diferentes ao mesmo tempo e até 40 números diferentes incluídos em 30 dias (acima, 409 `call_test_numbers_limit`: o piloto é para testar, não para trocar a lista a cada ligação). Vale na próxima ligação, sem reconectar o número. Um número brasileiro de celular casa com a grafia sem o nono dígito, como o WhatsApp às vezes informa.\n\nIdempotente por si: a mesma lista (em qualquer ordem) não muda nada (`changes` vazios); `Idempotency-Key` é aceita, não necessária. Cada inclusão e remoção fica registrada (quem criou a chave, qual chave, quando).\n\nEscopo: `calls:admin`.",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:admin"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "phones"
                ],
                "properties": {
                  "phones": {
                    "type": "array",
                    "maxItems": 100,
                    "items": {
                      "type": "string",
                      "pattern": "^\\+[1-9][0-9]{6,14}$"
                    }
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "phones": [
                  "+5511900000001",
                  "+5541900000002"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Como o GET, com `changes`: `{added, removed}` (telefones incluídos e removidos agora).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "trial",
                        "limit",
                        "numbers",
                        "changes"
                      ],
                      "properties": {
                        "trial": {
                          "type": "boolean"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "numbers": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "changes": {
                          "type": "object",
                          "required": [
                            "added",
                            "removed"
                          ],
                          "properties": {
                            "added": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "removed": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "trial": true,
                    "limit": 20,
                    "numbers": [
                      {
                        "phone": "+5511900000001",
                        "added_at": "2026-11-03T13:20:00.000Z"
                      },
                      {
                        "phone": "+5541900000002",
                        "added_at": "2026-11-03T13:20:00.000Z"
                      }
                    ],
                    "changes": {
                      "added": [
                        "+5541900000002"
                      ],
                      "removed": [
                        "+5511900000009"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input` (telefone fora do E.164, mais de 100 itens), `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `organization_key_required`, `owner_or_admin_required`, `organization_suspended`"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`call_trial_not_enabled` (piloto desligado), `call_test_numbers_limit` (mais de 20 números diferentes, ou mais de 40 incluídos em 30 dias)"
          }
        }
      }
    },
    "/v1/workspaces": {
      "get": {
        "summary": "Listar áreas de trabalho",
        "operationId": "get-v1-workspaces",
        "description": "Em ordem de nome. Uma chave presa a uma área de trabalho vê só ela.\n\n**Páginas:** `limit` (1 a 200, padrão 200) e `cursor`. Quando há mais, a resposta traz `next_cursor`; repita com `cursor=<next_cursor>` até vir `null`. Sem parâmetros, a resposta é a de sempre (as primeiras 200) mais `next_cursor`. Cursor inválido (ou de outra lista): 400 `invalid_cursor`.\n\nEscopo: `workspaces:read`.",
        "tags": [
          "Áreas de trabalho e operações"
        ],
        "x-scopes": [
          "workspaces:read"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Itens por página (1 a 200).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 200
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "`next_cursor` da página anterior (opaco).",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Áreas de trabalho da organização.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "maxItems": 200,
                      "items": {
                        "$ref": "#/components/schemas/Workspace"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor da próxima página; `null` na última."
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "2f1e0d9c-8b7a-4c5d-9e6f-0a1b2c3d4e5f",
                      "organization_id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a",
                      "name": "Atendimento"
                    }
                  ],
                  "next_cursor": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input` (`limit` fora de 1 a 200), `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          }
        }
      }
    },
    "/v1/owner-invitations/preview": {
      "post": {
        "summary": "Abrir um convite para ser dono",
        "operationId": "post-v1-owner-invitations-preview",
        "description": "**Sem chave de API.** A página do console \"Aceitar convite para ser dono\" mostra a conta criada pela equipe FlowZap, o e-mail convidado (mascarado) e se esse e-mail já tem cadastro confirmado. O link vale 7 dias. O token vai no corpo, para não ficar em registros de acesso. Limite: 30 pedidos a cada 15 minutos por endereço de origem.\n\nSem autenticação por chave de API.",
        "tags": [
          "Convite de dono"
        ],
        "x-scopes": [],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{43}$",
                    "description": "Token do link do convite: o que vem depois de `#convite-dono=` no e-mail. Vai no corpo, nunca no endereço."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "O convite está aberto.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OwnerInvitation"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error",
            "description": "`invitation_not_found`: link desconhecido, vencido, cancelado ou já usado (sempre a mesma resposta)."
          },
          "429": {
            "$ref": "#/components/responses/Error",
            "description": "`rate_limited`"
          }
        }
      }
    },
    "/v1/owner-invitations/accept": {
      "post": {
        "summary": "Aceitar um convite para ser dono",
        "operationId": "post-v1-owner-invitations-accept",
        "description": "**Sem chave de API.** E-mail sem cadastro confirmado: o corpo `{token, name, password}` (senha de 12 a 128 caracteres, a mesma regra do cadastro) cria a pessoa com o e-mail já confirmado e a torna dona (um cadastro ainda não confirmado desse e-mail é aproveitado, com o nome e a senha novos); depois ela entra pelo login. E-mail com cadastro confirmado: a pessoa entra no console antes e envia `{token}` com `Authorization: Bearer` da sessão dela; o e-mail da sessão precisa ser o convidado. Limite: 10 pedidos a cada 15 minutos por endereço de origem.\n\nSem autenticação por chave de API.",
        "tags": [
          "Convite de dono"
        ],
        "x-scopes": [],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "token",
                      "name",
                      "password"
                    ],
                    "properties": {
                      "token": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9_-]{43}$"
                      },
                      "name": {
                        "type": "string",
                        "minLength": 2,
                        "maxLength": 80
                      },
                      "password": {
                        "type": "string",
                        "minLength": 12,
                        "maxLength": 128
                      }
                    }
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "token"
                    ],
                    "description": "Só o token, com a sessão do console de quem já tem cadastro.",
                    "properties": {
                      "token": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9_-]{43}$"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A pessoa agora é dona da conta.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "organization_id"
                      ],
                      "properties": {
                        "organization_id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Error",
            "description": "`unauthorized`: a sessão do console enviada não vale."
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`invitation_email_mismatch`: a sessão é de outro e-mail."
          },
          "404": {
            "$ref": "#/components/responses/Error",
            "description": "`invitation_not_found`: link desconhecido, vencido, cancelado ou já usado."
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`account_exists`: o e-mail já tem cadastro confirmado; entre no console e aceite com a sua sessão."
          },
          "429": {
            "$ref": "#/components/responses/Error",
            "description": "`rate_limited`"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`retry`: conflito momentâneo; tente de novo."
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        }
      ],
      "get": {
        "summary": "Ler uma área de trabalho",
        "operationId": "get-v1-workspaces-workspaceId",
        "description": "Escopo: `workspaces:read`.",
        "tags": [
          "Áreas de trabalho e operações"
        ],
        "x-scopes": [
          "workspaces:read"
        ],
        "responses": {
          "200": {
            "description": "A área de trabalho.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Workspace"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        }
      ],
      "post": {
        "summary": "Criar número",
        "operationId": "post-v1-workspaces-workspaceId-instances",
        "description": "Cria o número (ainda sem WhatsApp conectado). Exige `Idempotency-Key`. Chave presa a um número não pode criar outro.\n\nEscopo: `instances:write`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "instances:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInstanceInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Repetição de um pedido já atendido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Instance"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Criado. Uma repetição com a mesma `Idempotency-Key` responde 200 com `Idempotent-Replay: true`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Instance"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `idempotency_key_required`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`"
          },
          "429": {
            "$ref": "#/components/responses/Error",
            "description": "`draft_limit_reached`"
          }
        }
      },
      "get": {
        "summary": "Listar números",
        "operationId": "get-v1-workspaces-workspaceId-instances",
        "description": "Os números da área de trabalho, os mais novos primeiro, com a mesma situação que o console mostra na visão geral. Uma chave presa a um número vê só ele; presa a outra área de trabalho, 404.\n\n**Páginas:** `limit` (1 a 200, padrão 200) e `cursor`. Quando há mais, a resposta traz `next_cursor`; repita o pedido com `cursor=<next_cursor>` até vir `null`. Sem parâmetros, a resposta é a de sempre (os primeiros 200) mais `next_cursor`. Um cursor inválido (ou de outra lista) responde 400 `invalid_cursor`.\n\n**Telefone do número:** `phone_masked` para qualquer chave com acesso; `phone` (completo, E.164) só para chaves com `instances:read` — é o número da própria empresa conectado ao WhatsApp. `last_phone_masked` é o telefone mascarado da última conexão (mesmo depois que o celular desconectou): é com ele que se lê o QR ao reconectar. `phone_changed` é `true` quando o número foi reconectado com outro telefone.\n\n`session_status`: `none` (ainda sem sessão), `unpaired` (sem vaga reservada), `reservation_expired` (a reserva para conectar venceu), `awaiting_worker`, `partial_worker` e `awaiting_start` (preparando a conexão), `connected` (conectado e enviando), `unavailable` (conectado, mas fora do ar agora), ou a situação da sessão (`pairing`, `reconnecting`, `offline`, `needs_pairing`, `revoked`, `blocked`, `paused`). Para os detalhes de um número, `GET …/instances/{instanceId}/status`.\n\nEscopo: `instances:read` (ou `engine:read`).",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "instances:read",
          "engine:read"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Itens por página (1 a 200).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 200
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "`next_cursor` da página anterior (opaco).",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Números da área de trabalho.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor da próxima página; `null` na última."
                    },
                    "data": {
                      "type": "array",
                      "maxItems": 200,
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "workspace_id",
                          "name",
                          "state",
                          "session_status",
                          "created_at",
                          "sign_messages",
                          "import_history",
                          "calls_enabled",
                          "phone_masked",
                          "last_phone_masked",
                          "phone_changed"
                        ],
                        "properties": {
                          "phone": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Telefone completo (E.164) da conta de WhatsApp conectada; só com `instances:read`."
                          },
                          "phone_masked": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Telefone mascarado, ex.: `+55 11 9****-1234`."
                          },
                          "last_phone_masked": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Telefone mascarado da conexão mais recente, atual ou encerrada (ex.: o que o celular desconectou); `null` se o número nunca conectou."
                          },
                          "phone_changed": {
                            "type": "boolean",
                            "description": "O telefone conectado agora é outro que o de antes da última reconexão."
                          },
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "workspace_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "draft",
                              "provisioning",
                              "active",
                              "archived"
                            ]
                          },
                          "session_status": {
                            "type": "string"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "sign_messages": {
                            "type": "boolean",
                            "description": "Envios do console levam o nome de quem enviou."
                          },
                          "import_history": {
                            "type": "boolean",
                            "description": "O histórico que o celular manda ao conectar é guardado (ver `/settings/history`)."
                          },
                          "calls_enabled": {
                            "type": "boolean",
                            "description": "O número tem ligações ativas."
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "8a4f2b8e-3c1d-4e5f-9a7b-1c2d3e4f5a6b",
                      "workspace_id": "2f1e0d9c-8b7a-4c5d-9e6f-0a1b2c3d4e5f",
                      "name": "Atendimento",
                      "state": "active",
                      "session_status": "connected",
                      "created_at": "2026-10-01T12:00:00.000Z",
                      "sign_messages": true,
                      "import_history": true,
                      "calls_enabled": false,
                      "phone": "+5511912345678",
                      "phone_masked": "+55 11 9****-5678",
                      "last_phone_masked": "+55 11 9****-5678",
                      "phone_changed": false
                    }
                  ],
                  "next_cursor": "aTo4YTRmMmI4ZS0zYzFkLTRlNWYtOWE3Yi0xYzJkM2U0ZjVhNmI"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input` (`limit` fora de 1 a 200), `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "patch": {
        "summary": "Renomear número",
        "operationId": "patch-number",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstanceRenameInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Nome alterado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/InstanceRenamed"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "summary": "Excluir número",
        "operationId": "delete-number",
        "description": "Libera a vaga e cancela a fila. O número precisa estar desconectado antes (`POST /disconnect`).\n\nEscopo: `engine:write`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "responses": {
          "200": {
            "description": "Excluído.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/InstanceDeleted"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`disconnect_first`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/connect": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Iniciar conexão por QR code",
        "operationId": "post-number-connect",
        "description": "Reserva a vaga e inicia o pareamento; leia o QR em `GET /qr`. Com `phone` (pareamento por código no telefone) responde **501 `not_supported_by_engine`**.\n\n**Reconectar um número já usado.** Quando o celular desconectou o número (`session_state` `needs_pairing` ou `revoked`) ou uma reconexão anterior venceu sem leitura do QR, a mesma rota começa um pareamento novo no mesmo número: a sessão antiga é encerrada, a vaga do número é trocada pela nova reserva (não ocupa outra vaga do plano, mesmo no limite) e os envios ainda na fila (`queued`) são cancelados com `message.canceled`. Conversas, campanhas, ajustes e a sequência de eventos do número continuam. Pode ler o QR com outro telefone: a lista de números mostra `last_phone_masked` antes e `phone_changed` depois. Repetir enquanto a tentativa está em andamento devolve a mesma reserva (200).\n\nNão reconecta (409): `number_still_linked` (o número continua ligado ao WhatsApp — conectado, reconectando ou fora do ar; use `POST …/restart`), `number_blocked` (bloqueio do WhatsApp), `number_paused` (outra sessão assumiu ou a versão foi recusada), `pairing_recovery_required` (a tentativa anterior ainda está sendo encerrada), `invalid_instance_state` (número excluído ou arquivado).\n\nEscopo: `engine:write`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstanceConnectInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reserva já existente.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SlotReservation"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Reserva criada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SlotReservation"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_instance_state`, `pairing_recovery_required`, `number_still_linked`, `number_blocked`, `number_paused`"
          },
          "429": {
            "$ref": "#/components/responses/Error",
            "description": "`slot_limit_reached`, `workspace_slot_limit_reached`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/disconnect": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Desconectar (sair do WhatsApp)",
        "operationId": "post-number-disconnect",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `not_logged_in`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/limits": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Limites de novas conversas",
        "operationId": "get-number-limits",
        "description": "Quando o WhatsApp limita o número a não iniciar conversas novas por um tempo, ele avisa o aparelho; cada aviso vira o evento `instance.reachout_timelock`. Esta rota mostra o **último aviso**: o motor não tem como perguntar o estado ao WhatsApp, então `unknown` significa que nenhum aviso chegou desde a conexão do número (não que não haja limite).\n\nEscopo: `instances:read` (ou `engine:read`).",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "instances:read",
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Estado segundo o último aviso do WhatsApp.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "state",
                        "limited_until",
                        "enforcement_type",
                        "observed_at",
                        "event_id"
                      ],
                      "properties": {
                        "state": {
                          "type": "string",
                          "enum": [
                            "limited",
                            "normal",
                            "unknown"
                          ],
                          "description": "`limited`: não inicie conversas novas até `limited_until` (ou até novo aviso, se `null`); `normal`: o último aviso liberou ou o prazo passou; `unknown`: nenhum aviso recebido."
                        },
                        "limited_until": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "enforcement_type": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Tipo de restrição informado pelo WhatsApp."
                        },
                        "observed_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time",
                          "description": "Quando o último aviso chegou."
                        },
                        "event_id": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uuid",
                          "description": "Evento `instance.reachout_timelock` do último aviso (`GET /v1/events/{id}`)."
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/proxy": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Ler proxy do número",
        "operationId": "get-number-proxy",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Proxy configurado (senha nunca aparece) ou null.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/ProxyView"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "summary": "Definir proxy do número",
        "operationId": "put-number-proxy",
        "description": "Vale a partir da próxima conexão (`POST /restart`). O endereço fica cifrado.\n\nEscopo: `engine:write`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProxyInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Proxy salvo.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ProxyView"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_proxy_url`, `proxy_host_not_allowed`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "summary": "Remover proxy",
        "operationId": "delete-number-proxy",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "responses": {
          "200": {
            "description": "Removido; `data` é null.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "null"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/proxy/managed": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Proxy gerenciado",
        "operationId": "get-number-proxy-managed",
        "description": "**Não suportado pelo motor do WhatsApp usado hoje.** O FlowZap ainda não oferece proxy próprio; use o seu com `PUT /proxy`. A rota existe, autentica e responde 501 `not_supported_by_engine` (não adianta repetir).\n\nEscopo: `engine:read`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "x-status": "not_supported",
        "responses": {
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "501": {
            "$ref": "#/components/responses/NotSupported"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/qr": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Ler o QR code de pareamento",
        "operationId": "get-number-qr",
        "description": "`ready` traz o código para gerar o QR; `pending` (202) ainda está preparando; `linked` já está conectado. Um número que o celular desconectou nunca é `linked`: responde `pending` com `session_state` `needs_pairing` (ou `revoked`) até `POST …/connect` começar a reconexão.\n\nEscopo: `engine:read`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "QR pronto ou número já conectado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PairingQr"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "QR ainda não disponível (`status: pending`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PairingQr"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/queue": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Ver a fila de envios",
        "operationId": "get-number-queue",
        "description": "Escopo: `messages:read` (ou `instances:read`).",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "messages:read",
          "instances:read"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Contagem por estado e envios pendentes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/QueueView"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "summary": "Cancelar envios na fila",
        "operationId": "delete-number-queue",
        "description": "Cancela o que ainda não saiu (`queued`). Cada envio cancelado gera o evento `message.canceled`.\n\nEscopo: `messages:send`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "responses": {
          "200": {
            "description": "Quantos envios foram cancelados.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "canceled"
                      ],
                      "properties": {
                        "canceled": {
                          "type": "integer",
                          "minimum": 0
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/reservations": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Reservar vaga para conectar",
        "operationId": "post-number-reservations",
        "description": "Reserva a vaga do plano para parear o número. Repetir devolve a mesma reserva (200). Num número já usado que o celular desconectou, reconecta como `POST …/connect`.\n\nEscopo: `instances:write`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "instances:write"
        ],
        "responses": {
          "200": {
            "description": "Reserva já existente.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SlotReservation"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Reserva criada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SlotReservation"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_instance_state`, `pairing_recovery_required`, `number_still_linked`, `number_blocked`, `number_paused`"
          },
          "429": {
            "$ref": "#/components/responses/Error",
            "description": "`slot_limit_reached`, `workspace_slot_limit_reached`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/restart": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Reconectar a sessão",
        "operationId": "post-number-restart",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/settings/delay": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Ler intervalo entre envios",
        "operationId": "get-number-settings-delay",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Intervalo atual (0 e 0 = sem pausa).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SendDelay"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "summary": "Definir intervalo entre envios",
        "operationId": "put-number-settings-delay",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendDelay"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Intervalo salvo.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SendDelay"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/settings/signature": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Ler assinatura do atendente",
        "operationId": "get-number-settings-signature",
        "description": "Com a assinatura ligada, as respostas enviadas pelo console começam com o nome de quem respondeu, em negrito e numa linha só (`*Ana:*` e, na linha de baixo, o texto). Vale para texto, legenda de foto, vídeo e documento, e a correção de uma mensagem assinada mantém o nome. Envios pela API não têm atendente e saem sem assinatura.\n\nEscopo: `engine:read`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Estado atual (ligada por padrão; desligar fica gravado).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Signature"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "summary": "Ligar ou desligar assinatura do atendente",
        "operationId": "put-number-settings-signature",
        "description": "Escopo: `engine:write`. Vale para as próximas respostas do console; mensagens já aceitas não mudam.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Signature"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Assinatura salva.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Signature"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/settings/history": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Ler importação de histórico",
        "operationId": "get-number-settings-history",
        "description": "Ligada (padrão), as conversas que o celular manda logo depois de conectar o número (até 90 dias, 50 mensagens por conversa) são guardadas como histórico: aparecem em `/chats`, nunca geram `message.received`. Desligada, nada desse histórico automático é guardado; um pedido explícito em `POST /chats/{jid}/history-sync` continua sendo atendido.\n\nEscopo: `engine:read`.",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Estado atual (ligada por padrão; desligar fica gravado).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/HistoryImport"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "summary": "Ligar ou desligar importação de histórico",
        "operationId": "put-number-settings-history",
        "description": "Escopo: `engine:write`. Vale para o histórico que chegar depois; o que já foi guardado continua (apague pela exclusão de dados da conta).",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HistoryImport"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Importação salva.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/HistoryImport"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/status": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Situação do número",
        "operationId": "get-number-status",
        "description": "Situação do número lida do banco (sem ir ao WhatsApp). `phone` (telefone completo do próprio número) só aparece para chaves com `instances:read`; `disconnect_reason` e `last_connection_event` dizem por que ele parou, a partir do último evento `instance.connection`.\n\n**Vocabulário.** Esta rota traz `session_state` (a situação crua da sessão) e `connected`; a lista `GET /v1/workspaces/{id}/instances` traz `session_status`, que resume a mesma situação com a reserva da vaga e o serviço do número:\n\n| `session_status` (lista) | `session_state` (aqui) | Quer dizer |\n|---|---|---|\n| `none` | `null` | Número criado, ainda sem sessão (`POST …/connect`). |\n| `unpaired` | `unpaired` | Sessão sem vaga reservada. |\n| `reservation_expired` | `unpaired` | A reserva para conectar venceu; peça outra. |\n| `awaiting_worker`, `partial_worker`, `awaiting_start` | `unpaired` | Preparando a conexão (o QR vem a seguir). |\n| `pairing` | `pairing` | Esperando a leitura do QR (`GET …/qr`). |\n| `connected` | `connected` (com `connected: true`) | Conectado e enviando. |\n| `unavailable` | `connected` ou `reconnecting` (com `connected: false`) | O WhatsApp está conectado, mas o serviço do número está fora do ar agora (`disconnect_reason: worker_unavailable`). |\n| `reconnecting`, `offline` | igual | Queda de conexão; o FlowZap tenta reconectar. |\n| `needs_pairing`, `revoked` | igual | Desconectado pelo celular: reconecte com `POST …/connect` e leia o novo QR em `GET …/qr`. |\n| `blocked` | `blocked` | Bloqueio do WhatsApp (`disconnect_reason: temporary_ban`). |\n| `paused` | `paused` | Outra sessão assumiu ou a versão foi recusada. |\n\nEscopo: `instances:read` (ou `engine:read`, sem `phone`).",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "instances:read",
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Situação atual.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/InstanceStatus"
                    }
                  }
                },
                "examples": {
                  "conectado": {
                    "summary": "Conectado (chave com instances:read)",
                    "value": {
                      "data": {
                        "id": "8a4f2b8e-3c1d-4e5f-9a7b-1c2d3e4f5a6b",
                        "name": "Atendimento",
                        "state": "active",
                        "session_state": "connected",
                        "connected": true,
                        "phone": "+5511912345678",
                        "phone_masked": "+55 11 9****-5678",
                        "disconnect_reason": null,
                        "last_connection_event": {
                          "state": "connected",
                          "session_state": "connected",
                          "reason": null,
                          "ban_expires_at": null,
                          "observed_at": "2026-10-30T09:00:00.000Z",
                          "event_id": "0b6c1e2d-3f4a-4b5c-8d9e-0f1a2b3c4d5e"
                        },
                        "worker_alive": true,
                        "lease_until": "2026-10-30T12:01:00.000Z",
                        "reservation_state": "occupied",
                        "reservation_expires_at": null,
                        "created_at": "2026-10-01T12:00:00.000Z"
                      }
                    }
                  },
                  "desconectado": {
                    "summary": "Desconectado pelo celular",
                    "value": {
                      "data": {
                        "id": "8a4f2b8e-3c1d-4e5f-9a7b-1c2d3e4f5a6b",
                        "name": "Atendimento",
                        "state": "active",
                        "session_state": "needs_pairing",
                        "connected": false,
                        "phone": "+5511912345678",
                        "phone_masked": "+55 11 9****-5678",
                        "disconnect_reason": "logged_out",
                        "last_connection_event": {
                          "state": "logged_out",
                          "session_state": "needs_pairing",
                          "reason": "LoggedOutReasonUnknown",
                          "ban_expires_at": null,
                          "observed_at": "2026-10-30T11:42:00.000Z",
                          "event_id": "1c7d2e3f-4a5b-4c6d-9e0f-1a2b3c4d5e6f"
                        },
                        "worker_alive": true,
                        "lease_until": "2026-10-30T12:01:00.000Z",
                        "reservation_state": "occupied",
                        "reservation_expires_at": null,
                        "created_at": "2026-10-01T12:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/capabilities": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "O que esta conexão pode fazer",
        "operationId": "get-number-capabilities",
        "description": "Matriz de capacidades do número agora, lida do FlowZap (sem ir ao WhatsApp; não gera operação). Serve para a integração decidir antes de chamar: se pode enviar (e por que não), quais tipos de mensagem a API aceita, janelas de edição e de apagar, ligações, gravação, limites e o que o WhatsApp Web não oferece.\n\n- `can_send` / `can_send_reason`: as mesmas regras de `POST …/messages` — `number_not_connected` (503 ao enviar), `numbers_over_limit` (409: a conta passou dos números do plano), `send_unavailable` (503: sem o envio liberado no plano ou sem a vaga do número). `null` quando pode enviar.\n- `new_conversations`: `limited` quando o último aviso do WhatsApp proíbe iniciar conversas novas (`GET …/limits`).\n- `message_types` vem do próprio contrato de envio: o que aparece aqui é aceito por `POST …/messages` (publicações de status ficam em `…/status-posts`). `forward` e `lid.send` refletem o que a versão em produção aceita.\n- `edit.window_minutes` e `revoke.window_hours` são as janelas do WhatsApp; apagar mensagem de outra pessoa em grupo exige ser admin.\n- `calls.mode`: `off`, `test_callers` (beta: só os números de teste da conta) ou `any_caller` (módulo de ligações contratado). Sem vídeo, sem ligação em grupo e sem transferência (veja `unsupported`).\n- `limits.queue` é o máximo de envios aguardando na fila do número (plano); `send_rate_per_minute`/`send_burst` são por chave e número.\n- `engine.version` é `null` enquanto a versão do motor não é publicada.\n\nEscopo: `instances:read` (ou `engine:read`).",
        "tags": [
          "Números"
        ],
        "x-scopes": [
          "instances:read",
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Capacidades do número.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/NumberCapabilities"
                    }
                  }
                },
                "example": {
                  "data": {
                    "instance_id": "8a4f2b8e-3c1d-4e5f-9a7b-1c2d3e4f5a6b",
                    "connected": true,
                    "session_state": "connected",
                    "disconnect_reason": null,
                    "can_send": true,
                    "can_send_reason": null,
                    "new_conversations": "allowed",
                    "message_types": [
                      "text",
                      "image",
                      "video",
                      "document",
                      "audio",
                      "sticker",
                      "location",
                      "contact",
                      "reaction",
                      "poll",
                      "edit",
                      "revoke",
                      "forward",
                      "buttons",
                      "list",
                      "carousel"
                    ],
                    "text": true,
                    "media": [
                      "image",
                      "video",
                      "document",
                      "audio",
                      "sticker"
                    ],
                    "groups": {
                      "send": true,
                      "manage": true
                    },
                    "lid": {
                      "receive": true,
                      "send": true
                    },
                    "quote": true,
                    "react": true,
                    "edit": {
                      "supported": true,
                      "window_minutes": 15
                    },
                    "revoke": {
                      "supported": true,
                      "window_hours": 48,
                      "group_admin_required_for_others": true
                    },
                    "forward": true,
                    "mentions": true,
                    "history_import": true,
                    "on_demand_history": true,
                    "receipts": {
                      "individual": true,
                      "group": true
                    },
                    "tickets": true,
                    "calls": {
                      "enabled": true,
                      "mode": "any_caller",
                      "audio_ws": true,
                      "inbound": true,
                      "outbound": true
                    },
                    "recording": {
                      "enabled": false,
                      "module": false,
                      "retention_days": 7
                    },
                    "unsupported": [
                      "delete_for_me",
                      "contacts_create",
                      "contacts_delete",
                      "business_catalog",
                      "business_profile_edit",
                      "video_calls",
                      "group_calls",
                      "call_transfer"
                    ],
                    "limits": {
                      "send_rate_per_minute": 60,
                      "send_burst": 10,
                      "queue": 1000,
                      "api_rate_per_minute": 600
                    },
                    "engine": {
                      "kind": "whatsapp_web",
                      "version": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          }
        }
      }
    },
    "/v1/messages": {
      "get": {
        "summary": "Buscar envios por referência",
        "operationId": "get-v1-messages",
        "description": "Busca envios pela sua `client_reference` ou pelo ID no WhatsApp (`provider_message_id`): informe exatamente um dos dois. Devolve até `limit` envios (máximo 20), do mais novo ao mais antigo, só dentro do alcance da chave (organização, área de trabalho ou número a que ela pertence).\n\nUse na reconciliação: depois de um timeout ou de um resultado `unknown`, confira o que já foi aceito em vez de enviar de novo.\n\nEscopo: `messages:read`.",
        "tags": [
          "Mensagens e mídia"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "parameters": [
          {
            "name": "client_reference",
            "in": "query",
            "required": false,
            "description": "A referência enviada em `client_reference`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          },
          {
            "name": "provider_message_id",
            "in": "query",
            "required": false,
            "description": "ID da mensagem no WhatsApp (`3EB0…`).",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._:-]{4,128}$"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Envios encontrados (lista vazia se nenhum).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MessageDetail"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`: nenhuma ou as duas referências, ou `limit` fora de 1 a 20."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          }
        }
      }
    },
    "/v1/messages/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Consultar um envio",
        "operationId": "get-v1-messages-id",
        "description": "Estado atual, tentativa (com `outcome_code` quando falhou), recibos (entregue, lida), origem (`source`: `api` ou `console`) e atendente (`actor_label`). Numa mensagem enviada a um grupo, `receipts` fica vazio e `group_receipts` conta os participantes que receberam e leram (\"lida por X de Y\"); a lista por participante está em `GET /v1/messages/{id}/receipts`.\n\nEscopo: `messages:read`.",
        "tags": [
          "Mensagens e mídia"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "responses": {
          "200": {
            "description": "O envio.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MessageDetail"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/messages/{id}/receipts": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do envio.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Quem recebeu e leu (grupos)",
        "operationId": "get-v1-messages-id-receipts",
        "description": "Recibos por participante de uma mensagem enviada a um grupo: um item por pessoa, com o primeiro momento em que o celular dela confirmou o recebimento (`delivered_at`) e a leitura (`read_at`). Uma leitura também conta como recebida. `summary.delivered` é quem já recebeu (celular desligado ainda não conta) e `summary.read`, quem leu: \"lida por `read` de `delivered`\". Numa mensagem direta, `group` é `false` e a lista vem vazia (os recibos estão em `GET /v1/messages/{id}`).\n\n`participant` é o telefone quando o próprio WhatsApp o mostra no grupo. Um telefone que só a sessão do número conhece vem mascarado, salvo para chaves com `audiences:export` (a mesma regra de `GET …/groups/{jid}`); sem telefone conhecido, `null`.\n\nA primeira confirmação de um grupo leva o envio a `delivered` (`message.delivered`). Em grupos o envio não passa a `read`: a leitura é por participante. Todos os recibos são gravados, mas as confirmações seguintes geram no máximo um evento `message.receipt` por mensagem a cada 60 segundos (só o ID do envio, como os demais eventos), e não um por participante: ao receber o evento, consulte esta rota para a contagem atual. Em mensagens diretas, `message.receipt` continua chegando a cada recibo que não muda o estado.\n\nEscopo: `messages:read`.",
        "tags": [
          "Mensagens e mídia"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "responses": {
          "200": {
            "description": "Recibos por participante.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupReceipts"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/inbound/{inboxId}/media": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "inboxId",
          "in": "path",
          "required": true,
          "description": "ID da mensagem recebida (`resource_id` de `message.received`).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Baixar mídia recebida",
        "operationId": "get-number-inbound-inboxId-media",
        "description": "Baixa pelo WhatsApp a foto, vídeo, áudio ou documento de uma mensagem recebida. Se demorar, responde 202 com a operação; repita o mesmo pedido: ele reaproveita o download em andamento em vez de baixar de novo. Mensagem sem mídia responde 404 `media_not_found`.\n\nAceita intervalos de bytes (`Accept-Ranges: bytes`), para tocar e avançar áudio e vídeo: um intervalo `Range: bytes=a-b`, `bytes=a-` ou `bytes=-n` responde 206 com `Content-Range`; começando depois do fim, 416 `range_not_satisfiable` com `Content-Range: bytes */<tamanho>`; vários intervalos ou cabeçalho inválido recebem o arquivo inteiro (200). O intervalo vale quando o download já terminou (enquanto isso, 202 com a operação). Mídia de visualização única nunca é baixada (404 `media_not_found`).\n\nEscopo: `messages:read`.",
        "tags": [
          "Mensagens e mídia"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "responses": {
          "200": {
            "description": "Os bytes do arquivo, com o `Content-Type` original e `Content-Disposition: attachment`.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "206": {
            "description": "Parte do arquivo pedida em `Range`, com `Content-Range: bytes a-b/<tamanho>`.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound",
            "description": "`not_found`, `media_not_found`"
          },
          "416": {
            "$ref": "#/components/responses/Error",
            "description": "`range_not_satisfiable`: o intervalo começa depois do fim do arquivo; `Content-Range: bytes */<tamanho>`."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "O motor não conseguiu baixar (ex.: `media_expired`)."
          },
          "502": {
            "$ref": "#/components/responses/Error",
            "description": "`download_failed`, `outcome_unknown`"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/media": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Enviar arquivo de mídia (upload)",
        "operationId": "post-number-media",
        "description": "Corpo **binário** (não JSON): os bytes do arquivo, com `Content-Type` do arquivo e `?kind=`. Até 16 MiB. O arquivo fica cifrado e expira em 48 horas. Use o `id` devolvido em `media.id` no envio.\n\nEscopo: `messages:send`.",
        "tags": [
          "Mensagens e mídia"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "parameters": [
          {
            "name": "kind",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/MediaKind"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          },
          "description": "Bytes do arquivo. O `Content-Type` real (ex.: `image/jpeg`) é o do arquivo. Nome opcional no cabeçalho `X-File-Name` (URL-encoded)."
        },
        "responses": {
          "201": {
            "description": "Mídia guardada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MediaObject"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_media_kind`, `invalid_file_name`, `invalid_body`, `empty_media`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound",
            "description": "`not_found`"
          },
          "413": {
            "$ref": "#/components/responses/Error",
            "description": "`media_too_large`"
          },
          "415": {
            "$ref": "#/components/responses/Error",
            "description": "`mime_type_required`, `unsupported_media_type`, `media_content_mismatch`: tipo ausente, não aceito para o `kind`, ou conteúdo que não bate com o tipo. Para `kind=audio` também é aceito `audio/webm` (gravação do navegador), que só pode ser enviado com `ptt: true`."
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/media/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Ler dados de uma mídia",
        "operationId": "get-number-media-id",
        "description": "Escopo: `messages:read`.",
        "tags": [
          "Mensagens e mídia"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "responses": {
          "200": {
            "description": "Metadados (nunca os bytes).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MediaObject"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "summary": "Apagar uma mídia",
        "operationId": "delete-number-media-id",
        "description": "Escopo: `messages:send`.",
        "tags": [
          "Mensagens e mídia"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "responses": {
          "204": {
            "description": "Feito, sem corpo."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/status-posts": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Publicar no Status",
        "operationId": "post-number-status-posts",
        "description": "Publica no Status (stories) do WhatsApp do número: texto com cor de fundo e fonte, ou foto/vídeo com legenda. É um envio como os de `POST .../messages` (`type: status`): entra na fila, o resultado chega pelos eventos `message.*` e pode ser acompanhado em `GET /v1/messages/{id}`.\n\n**Quem vê:** a privacidade do Status escolhida no celular (Configurações › Privacidade › Status): \"Meus contatos\", \"Meus contatos, exceto…\" ou \"Compartilhar só com…\". A FlowZap não escolhe nem guarda lista de quem vê.\n\nTexto: até 700 caracteres, sempre em branco; `background_color` em `#RRGGBB` (padrão `#075E54`) e `font` com o nome da fonte do WhatsApp (padrão `system`). Foto ou vídeo: `media_id` de um upload (`POST .../media`) ou `media_url` https — um dos dois. Vídeos do Status costumam ter até 1 minuto.\n\nSe o número não conseguir publicar em 6 horas (celular desligado, por exemplo), a publicação expira (`state: expired`) e não sai mais tarde.\n\nExige `Idempotency-Key`: repetir o mesmo pedido devolve a mesma publicação (`Idempotent-Replay: true`) e nunca publica duas vezes. Mesmo limite de envios de `POST .../messages` (429 `rate_limited`/`queue_full`), plano ativo e pausa por números acima do plano.\n\nEscopo: `engine:write`.",
        "tags": [
          "Mensagens e mídia"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "required": [
                      "type",
                      "text"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "text"
                        ]
                      },
                      "text": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 700
                      },
                      "background_color": {
                        "type": "string",
                        "pattern": "^#[0-9a-fA-F]{6}$",
                        "description": "Cor de fundo, ex.: `#075E54`."
                      },
                      "font": {
                        "$ref": "#/components/schemas/StatusFont"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "required": [
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "image",
                          "video"
                        ]
                      },
                      "media_id": {
                        "type": "string",
                        "format": "uuid",
                        "description": "Mídia enviada antes em `POST .../media` (`kind` igual a `type`)."
                      },
                      "media_url": {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 2048,
                        "description": "Link https que o servidor baixa (até 16 MiB)."
                      },
                      "caption": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 1024
                      }
                    },
                    "additionalProperties": false
                  }
                ]
              },
              "example": {
                "type": "text",
                "text": "Promoção só hoje!",
                "background_color": "#128C7E",
                "font": "calistoga_regular"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Aceita na fila.",
            "headers": {
              "Idempotent-Replay": {
                "$ref": "#/components/headers/IdempotentReplay"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/MessageCommand"
                        },
                        {
                          "type": "object",
                          "required": [
                            "type"
                          ],
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": [
                                "text",
                                "image",
                                "video"
                              ]
                            }
                          }
                        }
                      ]
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `idempotency_key_required`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound",
            "description": "`not_found`, `media_not_found`"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`, `numbers_over_limit`. `numbers_over_limit`: a conta passou 7 dias com mais números do que o plano permite; publicar fica pausado até remover os números excedentes."
          },
          "413": {
            "$ref": "#/components/responses/Error",
            "description": "`media_too_large`"
          },
          "415": {
            "$ref": "#/components/responses/Error",
            "description": "`unsupported_media_type`, `media_content_mismatch`"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`media_kind_mismatch`, `media_url_blocked`, `media_url_failed`, `media_url_timeout`, `media_url_content_type`, `media_url_redirects`, `media_url_unresolvable`"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `send_unavailable`. `send_unavailable`: número desconectado ou sem plano ativo."
          }
        }
      },
      "get": {
        "summary": "Listar publicações no Status",
        "operationId": "get-number-status-posts",
        "description": "As publicações no Status feitas por este número pela FlowZap (API, console ou `POST .../messages` com `type: status`), da mais recente para a mais antiga. Não traz o conteúdo nem quem viu.\n\nEscopo: `engine:read`.",
        "tags": [
          "Mensagens e mídia"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Quantas publicações (1 a 100, padrão 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "As publicações.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "type",
                          "state",
                          "provider_message_id",
                          "outcome_code",
                          "expires_at",
                          "created_at"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid",
                            "description": "Mesmo ID de `GET /v1/messages/{id}`."
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "text",
                              "image",
                              "video",
                              "audio"
                            ]
                          },
                          "state": {
                            "type": "string",
                            "description": "Estado do envio, como em `MessageCommand`."
                          },
                          "provider_message_id": {
                            "type": "string"
                          },
                          "outcome_code": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Motivo de uma falha (ex.: `media_upload_failed`, `invalid_status_style`)."
                          },
                          "expires_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/media/{id}/content": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Baixar uma mídia enviada",
        "operationId": "get-number-media-id-content",
        "description": "Aceita intervalos de bytes (`Accept-Ranges: bytes`), para tocar e avançar áudio e vídeo: um intervalo `Range: bytes=a-b`, `bytes=a-` ou `bytes=-n` responde 206 com `Content-Range`; começando depois do fim, 416 `range_not_satisfiable` com `Content-Range: bytes */<tamanho>`; vários intervalos ou cabeçalho inválido recebem o arquivo inteiro (200).\n\nEscopo: `messages:read`.",
        "tags": [
          "Mensagens e mídia"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "responses": {
          "200": {
            "description": "Os bytes do arquivo, com o `Content-Type` original e `Content-Disposition: attachment`.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "206": {
            "description": "Parte do arquivo pedida em `Range`, com `Content-Range: bytes a-b/<tamanho>`.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "416": {
            "$ref": "#/components/responses/Error",
            "description": "`range_not_satisfiable`: o intervalo começa depois do fim do arquivo; `Content-Range: bytes */<tamanho>`."
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/messages": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Enviar mensagem",
        "operationId": "post-number-messages",
        "description": "Aceita texto, mídia, localização, contato, reação, enquete, edição, apagar, encaminhar, botões, lista, carrossel (beta) e status. A resposta 202 só confirma que a mensagem entrou na fila; o resultado chega pelos eventos `message.*` e por `GET /v1/messages/{id}`.\n\nDestino (`to`): telefone (`phone`, conferido no WhatsApp), grupo (`group`) ou JID de uma conversa individual (`jid`, telefone ou LID, enviado direto). Citações, reações, edições, apagar e encaminhar apontam para qualquer mensagem guardada do número, enviada ou recebida (sem janela das mais recentes). `actor_label` (opcional, 1 a 80) identifica o atendente externo.\n\nGlossário de IDs:\n- `id` do envio (UUID): devolvido aqui; consulte em `GET /v1/messages/{id}`.\n- `provider_message_id`: o ID que a mensagem tem no WhatsApp (`3EB0…`).\n- ID da mensagem recebida (UUID): `resource_id` de `message.received`; usado em `GET …/inbound/{id}` e `GET …/inbound/{inboxId}/media`.\n- `message_id` em `reply_to`, `reaction`, `edit`, `revoke` e `forward`: o ID no WhatsApp de qualquer mensagem, enviada (`provider_message_id`) ou recebida (`message_id`).\n- `client_reference`: a sua referência; busque por ela em `GET /v1/messages?client_reference=…`.\n\nCiclo de estados: `queued` (na fila) → `dispatching` (o motor está enviando) → `provider_accepted` (o WhatsApp aceitou) → `delivered` (chegou ao aparelho) → `read` (lida; mensagens a grupos não chegam a `read`, a leitura é por participante em `GET /v1/messages/{id}/receipts`). Finais sem envio: `failed` (nada saiu; motivo em `attempt.outcome_code`), `expired` (passou de `expires_at` antes de sair), `canceled`. `unknown`: pode ter saído ou não (ex.: a conexão caiu durante o envio); nunca reenvie às cegas, consulte por `client_reference` ou espere os eventos.\n\n\"Apagar só para mim\" e outras ações locais do celular não são suportadas.\n\nExige `Idempotency-Key`: repetir o mesmo pedido devolve o mesmo envio (`Idempotent-Replay: true`) e nunca manda duas vezes.\n\nLimite por chave e número: 60 envios por minuto, com rajada de 10 (429 `rate_limited` + `Retry-After`). Com a fila do número no limite de envios aguardando do plano (`pending_messages` em `GET /v1/account`), novos pedidos recebem 429 `queue_full`.\n\nEscopo: `messages:send`.",
        "tags": [
          "Mensagens e mídia"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendMessage"
              },
              "examples": {
                "texto_telefone": {
                  "summary": "Texto para telefone",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "text",
                    "text": {
                      "body": "Seu pedido saiu para entrega."
                    },
                    "client_reference": "pedido-4821",
                    "expires_at": "2026-11-01T18:00:00Z",
                    "actor_label": "Ana (Atendimento)"
                  }
                },
                "texto_jid": {
                  "summary": "Texto para JID de telefone",
                  "value": {
                    "to": {
                      "kind": "jid",
                      "value": "5511912345678@s.whatsapp.net"
                    },
                    "type": "text",
                    "text": {
                      "body": "Olá!"
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "texto_lid": {
                  "summary": "Texto para LID",
                  "value": {
                    "to": {
                      "kind": "jid",
                      "value": "123456789012345@lid"
                    },
                    "type": "text",
                    "text": {
                      "body": "Olá!"
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "texto_grupo": {
                  "summary": "Texto para grupo",
                  "value": {
                    "to": {
                      "kind": "group",
                      "value": "120363012345678901@g.us"
                    },
                    "type": "text",
                    "text": {
                      "body": "Bom dia, equipe."
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "citacao_recebida": {
                  "summary": "Citar mensagem recebida",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "text",
                    "text": {
                      "body": "Sim, abrimos no sábado."
                    },
                    "reply_to": {
                      "message_id": "3A5F09C2B1E4D7A8C6F0"
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "citacao_enviada": {
                  "summary": "Citar mensagem enviada",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "text",
                    "text": {
                      "body": "Lembrete da mensagem acima."
                    },
                    "reply_to": {
                      "message_id": "3EB0A1B2C3D4E5F6071829"
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "citacao_midia": {
                  "summary": "Citar mídia em grupo",
                  "value": {
                    "to": {
                      "kind": "group",
                      "value": "120363012345678901@g.us"
                    },
                    "type": "text",
                    "text": {
                      "body": "Esta é a planta nova."
                    },
                    "reply_to": {
                      "message_id": "3A5F09C2B1E4D7A8C6F1",
                      "participant": "123456789012345@lid"
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "reacao": {
                  "summary": "Reação",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "reaction",
                    "reaction": {
                      "message_id": "3A5F09C2B1E4D7A8C6F0",
                      "emoji": "👍"
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "troca_reacao": {
                  "summary": "Trocar reação (nova reação substitui a anterior)",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "reaction",
                    "reaction": {
                      "message_id": "3A5F09C2B1E4D7A8C6F0",
                      "emoji": "❤️"
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "remover_reacao": {
                  "summary": "Remover reação",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "reaction",
                    "reaction": {
                      "message_id": "3A5F09C2B1E4D7A8C6F0",
                      "emoji": ""
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "edicao": {
                  "summary": "Editar (15 minutos)",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "edit",
                    "edit": {
                      "message_id": "3EB0A1B2C3D4E5F6071829",
                      "text": "Seu pedido sai às 15h."
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "apagar": {
                  "summary": "Apagar para todos (48 horas)",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "revoke",
                    "revoke": {
                      "message_id": "3EB0A1B2C3D4E5F6071829"
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "encaminhar": {
                  "summary": "Encaminhar",
                  "value": {
                    "to": {
                      "kind": "group",
                      "value": "120363012345678901@g.us"
                    },
                    "type": "forward",
                    "forward": {
                      "message_id": "3A5F09C2B1E4D7A8C6F0"
                    },
                    "expires_at": "2026-11-01T18:00:00Z",
                    "actor_label": "Ana (Atendimento)"
                  }
                },
                "midia_id": {
                  "summary": "Imagem por upload",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "image",
                    "media": {
                      "id": "3f9d0c52-8e1b-4a7f-b6d4-0c2e9a1f5b73"
                    },
                    "caption": "Cardápio de hoje",
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "midia_base64": {
                  "summary": "Imagem em base64",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "image",
                    "media": {
                      "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGNgYGD4DwABBAEAwS2OUAAAAABJRU5ErkJggg=="
                    },
                    "mime_type": "image/png",
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "midia_url": {
                  "summary": "Vídeo por link",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "video",
                    "media": {
                      "url": "https://exemplo.com.br/tour.mp4"
                    },
                    "caption": "Tour do imóvel",
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "audio_voz": {
                  "summary": "Mensagem de voz",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "audio",
                    "media": {
                      "id": "8a1d2c3b-4e5f-4a6b-9c7d-0e1f2a3b4c5d"
                    },
                    "ptt": true,
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "documento": {
                  "summary": "Documento",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "document",
                    "media": {
                      "url": "https://exemplo.com.br/contrato.pdf"
                    },
                    "file_name": "contrato.pdf",
                    "caption": "Contrato para assinatura",
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "figurinha": {
                  "summary": "Figurinha",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "sticker",
                    "media": {
                      "id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e"
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "mencao": {
                  "summary": "Menção em grupo (telefone e LID)",
                  "value": {
                    "to": {
                      "kind": "group",
                      "value": "120363012345678901@g.us"
                    },
                    "type": "text",
                    "text": {
                      "body": "@5511912345678 e @123456789012345, reunião às 10h."
                    },
                    "mentions": [
                      "+5511912345678",
                      "123456789012345@lid"
                    ],
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "contato": {
                  "summary": "Contato",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "contact",
                    "contacts": [
                      {
                        "name": "Corretor Paulo",
                        "phones": [
                          "+5511987654321"
                        ],
                        "organization": "Imobiliária"
                      }
                    ],
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "localizacao": {
                  "summary": "Localização",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "location",
                    "location": {
                      "latitude": -23.5614,
                      "longitude": -46.6559,
                      "name": "Plantão de vendas",
                      "address": "Av. Paulista, 1000"
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "enquete": {
                  "summary": "Enquete",
                  "value": {
                    "to": {
                      "kind": "group",
                      "value": "120363012345678901@g.us"
                    },
                    "type": "poll",
                    "poll": {
                      "name": "Melhor horário para visita?",
                      "options": [
                        "Manhã",
                        "Tarde"
                      ],
                      "selectable_count": 1
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "botoes": {
                  "summary": "Botões",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "buttons",
                    "buttons": {
                      "text": "Confirma a visita amanhã?",
                      "items": [
                        {
                          "id": "sim",
                          "title": "Sim"
                        },
                        {
                          "id": "nao",
                          "title": "Não"
                        }
                      ]
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                },
                "lista": {
                  "summary": "Lista",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "type": "list",
                    "list": {
                      "text": "Escolha o tipo de imóvel",
                      "button_text": "Ver opções",
                      "sections": [
                        {
                          "title": "Residencial",
                          "rows": [
                            {
                              "id": "apto",
                              "title": "Apartamento"
                            },
                            {
                              "id": "casa",
                              "title": "Casa"
                            }
                          ]
                        }
                      ]
                    },
                    "expires_at": "2026-11-01T18:00:00Z"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Aceita na fila.",
            "headers": {
              "Idempotent-Replay": {
                "$ref": "#/components/headers/IdempotentReplay"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MessageCommand"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input` (inclui `actor_label` inválido), `idempotency_key_required`, `invalid_expiry`, `invalid_media_url`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound",
            "description": "`not_found`, `media_not_found`, `target_not_found`. `target_not_found`: a mensagem citada, reagida, editada, apagada ou encaminhada não está entre as mensagens guardadas do número, ou é de outra conversa que não `to`."
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`, `numbers_over_limit`. `numbers_over_limit`: a conta passou 7 dias com mais números do que o plano permite; o envio fica pausado até remover os números excedentes (o recebimento continua). Apagar para todos (`revoke`) e remover uma reação (`emoji` vazio) continuam aceitos; edição, reação nova e demais envios, não. Repetir um envio já aceito devolve o mesmo resultado."
          },
          "413": {
            "$ref": "#/components/responses/Error",
            "description": "`media_too_large`, `voice_note_too_large`, `voice_note_too_long`, `carousel_media_too_large`. `voice_note_*`: a mensagem de voz convertida passaria de 16 MiB ou de 30 minutos. `carousel_media_too_large`: as mídias dos cartões somam mais de 32 MiB."
          },
          "415": {
            "$ref": "#/components/responses/Error",
            "description": "`mime_type_required`, `unsupported_media_type`, `media_content_mismatch`: tipo ausente, não aceito para o `type` (ex.: `audio/webm` sem `ptt: true`), ou conteúdo que não bate com o tipo."
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`audio_unreadable`, `target_not_editable`, `target_not_revocable`, `edit_window_expired`, `revoke_window_expired`, `not_group_admin`, `not_group_member`, `forward_not_supported`, `forward_not_allowed`, `forward_media_expired`, `forward_media_unavailable`, `forward_media_too_large`, `media_kind_mismatch`, `carousel_media_mixed`, `media_url_blocked`, `media_url_failed`, `media_url_timeout`, `media_url_content_type`, `media_url_redirects`, `media_url_unresolvable`. `not_group_admin` / `not_group_member`: apagar a mensagem de outro participante exige o número administrador do grupo. `forward_*`: ver `SendForward`."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `send_unavailable`, `audio_conversion_unavailable`, `target_index_building`. `send_unavailable`: número desconectado ou sem plano ativo. `audio_conversion_unavailable`: a conversão da mensagem de voz não pôde rodar agora; repita com a mesma `Idempotency-Key`. `target_index_building`: o número tem muitas mensagens recebidas ainda não indexadas para a busca por ID; cada tentativa indexa até 5000, repita com a mesma `Idempotency-Key`."
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/chats": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Listar conversas",
        "operationId": "get-number-chats",
        "description": "Da atividade mais recente para a mais antiga, a partir do histórico guardado pelo FlowZap (as 2000 mensagens mais recentes de cada origem: veja `window`). Para ler uma conversa inteira, sem esse limite, use `GET …/chats/{jid}/messages`.\n\nCada conversa traz o estado que ela tem no WhatsApp — `archived`, `pinned`, `muted`/`muted_until` — e as etiquetas (`labels`), feitos no celular (inclusive antes da conexão: a sincronização inicial do WhatsApp é aplicada) ou pela API. Uma mudança mais antiga nunca desfaz uma mais nova.\n\n`unread_count` conta as mensagens recebidas depois da nossa última resposta, não as não lidas do WhatsApp; a marca de leitura por pessoa existe só no console.\n\nConversas de grupo vêm misturadas às individuais, com `is_group: true` e `jid` do grupo (`…@g.us`); `name` é sempre `null` para grupos (o nome está em `GET …/groups`). As mensagens de um grupo (`GET …/chats/{jid}/messages`) trazem em `sender_jid` quem escreveu. Para responder no grupo, envie com `to: {\"kind\": \"group\", \"value\": \"…@g.us\"}`; respostas e reações a mensagens de um participante usam o mesmo `to`.\n\nEscopo: `messages:read`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            },
            "description": "Parte do nome, telefone ou JID."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512,
              "pattern": "^[A-Za-z0-9_-]{1,512}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Uma página de conversas.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ChatSummary"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "window": {
                      "$ref": "#/components/schemas/Window"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/chats/count": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Contar conversas",
        "operationId": "get-number-chats-count",
        "description": "Escopo: `messages:read`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "responses": {
          "200": {
            "description": "Totais.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "total",
                        "groups",
                        "unread_chats",
                        "unread_messages"
                      ],
                      "properties": {
                        "total": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "groups": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "unread_chats": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "unread_messages": {
                          "type": "integer",
                          "minimum": 0
                        }
                      },
                      "additionalProperties": false
                    },
                    "window": {
                      "$ref": "#/components/schemas/Window"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/chats/{jid}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/ChatJid"
          }
        }
      ],
      "delete": {
        "summary": "Apagar conversa no WhatsApp",
        "operationId": "delete-number-chats-jid",
        "description": "Apaga no aparelho; o histórico do FlowZap (auditoria e leituras pela API) continua.\n\nEscopo: `engine:write`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_jid`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_jid`, `invalid_payload`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/chats/{jid}/archive": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/ChatJid"
          }
        }
      ],
      "post": {
        "summary": "Arquivar ou desarquivar",
        "operationId": "post-number-chats-jid-archive",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "archive"
                ],
                "properties": {
                  "archive": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_jid`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_jid`, `invalid_payload`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/chats/{jid}/ephemeral": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/ChatJid"
          }
        }
      ],
      "post": {
        "summary": "Mensagens temporárias da conversa",
        "operationId": "post-number-chats-jid-ephemeral",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "seconds"
                ],
                "properties": {
                  "seconds": {
                    "type": "integer",
                    "enum": [
                      0,
                      86400,
                      604800,
                      7776000
                    ]
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_jid`, `private_chat_required`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_timer`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/chats/{jid}/history-sync": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/ChatJid"
          }
        }
      ],
      "post": {
        "summary": "Pedir mensagens antigas ao celular",
        "operationId": "post-number-chats-jid-history-sync",
        "description": "Pede ao celular até `count` mensagens anteriores à mais antiga que o FlowZap guardou desta conversa — a mais antiga que o próprio celular informou (recebida, vista no celular ou já importada), em qualquer grafia do contato, sem limite de janela; envios pela API não servem de âncora. Cada novo pedido vai mais para trás. Mesmas regras do botão \"Buscar mensagens anteriores\" do console:\n\n- um pedido por número a cada 30 s (`429 rate_limited`, com `Retry-After`); repetir com a mesma `Idempotency-Key` devolve o primeiro pedido, sem contar de novo;\n- recusado com `409 history_import_off` quando o número está com \"Importar histórico\" desligado;\n- `422 no_known_message` quando não há mensagem guardada desta conversa que o celular tenha informado.\n\nA resposta chega depois, só se o celular estiver online e ainda tiver essas mensagens; ela é guardada como histórico e aparece nas leituras de conversas (`/chats`, `…/messages`), sem gerar `message.received` em webhooks. Se o celular responder em até ~10 s, `data.stored` diz quantas mensagens novas foram guardadas (`0`: nada mais antigo do que já temos); sem `stored`, a resposta ainda pode chegar depois. Limites do WhatsApp: melhor esforço (o WhatsApp decide se o celular atende), até 50 por pedido, só o que ainda está no celular (mensagens apagadas, conversas limpas ou de outro aparelho não voltam), mídia antiga pode não ter download.\n\nEscopo: `engine:write`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50,
                    "default": 50
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_jid`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`history_import_off`: o número não importa histórico. `idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "`no_known_message`: nenhuma mensagem guardada desta conversa serve de âncora; ou a operação falhou no WhatsApp e `error.code` traz o motivo informado pelo motor (ex.: `invalid_count`)."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited",
            "description": "`rate_limited`: já houve um pedido de histórico deste número nos últimos 30 s."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/chats/{jid}/labels": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/ChatJid"
          }
        }
      ],
      "get": {
        "summary": "Etiquetas de uma conversa",
        "operationId": "get-number-chats-jid-labels",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Etiquetas aplicadas.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WhatsappLabel"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_jid`, `invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "summary": "Aplicar ou tirar etiqueta da conversa",
        "operationId": "post-number-chats-jid-labels",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "label_id",
                  "labeled"
                ],
                "properties": {
                  "label_id": {
                    "type": "string",
                    "pattern": "^\\d{1,20}$"
                  },
                  "labeled": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_jid`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/chats/{jid}/messages": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/ChatJid"
          }
        }
      ],
      "get": {
        "summary": "Mensagens de uma conversa",
        "operationId": "get-number-chats-jid-messages",
        "description": "Da mais nova para a mais antiga, todas as mensagens que o FlowZap guardou desta conversa (recebidas, vistas no celular, enviadas pela API ou pelo console, histórico importado), em todas as grafias conhecidas do contato: o JID pedido, o telefone ↔ LID que o WhatsApp provou ou que a equipe associou em Conversas, e as duas grafias de celular brasileiro (com e sem o nono dígito). Não depende da janela de 2000 mensagens das listas.\n\nPaginação: passe `next_before` em `before` até `end_of_history: true` (com `next_before: null`), que diz que não há nada mais antigo guardado pelo FlowZap. Para trazer mensagens que só o celular ainda tem, use `POST …/chats/{jid}/history-sync` e leia de novo. O cursor é assinado para esta conversa (o mesmo `jid`); usado em outra, responde `400 invalid_cursor`. Cursores emitidos antes desta versão continuam aceitos.\n\n`paging: \"conversation\"` é o modo normal. Logo depois de uma atualização do FlowZap, enquanto as mensagens antigas do número ainda estão sendo indexadas, a resposta pode vir da janela (`paging: \"window\"`, com `window.truncated` e `end_of_history: false` quando há mensagens fora dela); repita depois para ler tudo.\n\nEdições, exclusões e reações aparecem como mensagens próprias (`kind`), e o alvo carregado ganha `edits`/`revoked`; `applied` diz se a mudança valeu (veja `ChatHistoryMessage`).\n\nEscopo: `messages:read`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512,
              "pattern": "^[A-Za-z0-9_-]{1,512}$"
            },
            "description": "Valor de `next_before` da página anterior desta mesma conversa."
          }
        ],
        "responses": {
          "200": {
            "description": "Da mais nova para a mais antiga.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_before",
                    "end_of_history",
                    "paging",
                    "window"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ChatHistoryMessage"
                      }
                    },
                    "next_before": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor da próxima página (mais antiga); `null` no fim."
                    },
                    "end_of_history": {
                      "type": "boolean",
                      "description": "`true`: não há mensagem mais antiga guardada pelo FlowZap nesta conversa."
                    },
                    "paging": {
                      "type": "string",
                      "enum": [
                        "conversation",
                        "window"
                      ],
                      "description": "`conversation`: paginação pela conversa inteira (normal). `window`: resposta temporária a partir da janela de 2000 mensagens, enquanto o número é indexado."
                    },
                    "window": {
                      "$ref": "#/components/schemas/Window"
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "3EB0C431D2A1F0B5E7A9",
                      "chat_jid": "99887766554433@lid",
                      "direction": "in",
                      "from_me": false,
                      "sender_jid": "99887766554433@lid",
                      "sender_name": "Ana",
                      "source": "contact",
                      "kind": "text",
                      "text": "Pode mandar o orçamento?",
                      "timestamp": "2026-10-30T13:02:11.000Z",
                      "state": null,
                      "command_id": null
                    }
                  ],
                  "next_before": "WyIyMDI2LTEwLTMwVDEzOjAyOjExLjAwMFoiLCIzRUIwQzQzMUQyQTFGMEI1RTdBOSIsIm...",
                  "end_of_history": false,
                  "paging": "conversation",
                  "window": {
                    "rows_per_source": 2000,
                    "truncated": false,
                    "skipped": 0
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_jid`, `invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/chats/{jid}/mute": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/ChatJid"
          }
        }
      ],
      "post": {
        "summary": "Silenciar conversa",
        "operationId": "post-number-chats-jid-mute",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "mute"
                ],
                "properties": {
                  "mute": {
                    "type": "boolean"
                  },
                  "duration_seconds": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 31536000,
                    "description": "0 ou ausente: para sempre."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_jid`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_duration`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/chats/{jid}/pin": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/ChatJid"
          }
        }
      ],
      "post": {
        "summary": "Fixar ou desafixar conversa",
        "operationId": "post-number-chats-jid-pin",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "pin"
                ],
                "properties": {
                  "pin": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_jid`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_jid`, `invalid_payload`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/chats/{jid}/read": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/ChatJid"
          }
        }
      ],
      "post": {
        "summary": "Marcar conversa como lida ou não lida",
        "operationId": "post-number-chats-jid-read",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "read"
                ],
                "properties": {
                  "read": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_jid`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_jid`, `invalid_payload`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/labels": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Listar etiquetas do WhatsApp",
        "operationId": "get-number-labels",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Etiquetas conhecidas.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WhatsappLabel"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "summary": "Criar ou editar etiqueta",
        "operationId": "post-number-labels",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "color"
                ],
                "properties": {
                  "label_id": {
                    "type": "string",
                    "pattern": "^\\d{1,20}$",
                    "description": "Omitido: cria uma nova."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "color": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 19
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_color`, `invalid_name`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/labels/refresh": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Sincronizar etiquetas com o celular",
        "operationId": "post-number-labels-refresh",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "full_sync": {
                    "type": "boolean",
                    "default": false
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/labels/{labelId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "labelId",
          "in": "path",
          "required": true,
          "description": "ID da etiqueta do WhatsApp.",
          "schema": {
            "type": "string",
            "pattern": "^\\d{1,20}$"
          }
        }
      ],
      "delete": {
        "summary": "Apagar etiqueta",
        "operationId": "delete-number-labels-labelId",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_label_id`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/messages/read": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Marcar mensagens como lidas",
        "operationId": "post-number-messages-read",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Em grupo, `sender` (quem enviou) é obrigatório.",
                "required": [
                  "chat",
                  "message_ids"
                ],
                "properties": {
                  "chat": {
                    "$ref": "#/components/schemas/ChatJid"
                  },
                  "message_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "pattern": "^[A-Za-z0-9]{6,128}$"
                    },
                    "minItems": 1,
                    "maxItems": 50
                  },
                  "sender": {
                    "$ref": "#/components/schemas/UserJid"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `sender_required`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_message_ids`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/messages/search": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Buscar mensagens por texto",
        "operationId": "get-number-messages-search",
        "description": "Escopo: `messages:read`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 100
            }
          },
          {
            "name": "chat",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ChatJid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Mensagens encontradas.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ChatHistoryMessage"
                      }
                    },
                    "window": {
                      "$ref": "#/components/schemas/Window"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/messages/{messageId}/pin": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "messageId",
          "in": "path",
          "required": true,
          "description": "ID da mensagem no WhatsApp.",
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9]{6,128}$"
          }
        }
      ],
      "post": {
        "summary": "Fixar mensagem na conversa",
        "operationId": "post-number-messages-messageId-pin",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/MessageActionInput"
                  },
                  {
                    "type": "object",
                    "required": [
                      "pin"
                    ],
                    "properties": {
                      "pin": {
                        "type": "boolean"
                      },
                      "duration_seconds": {
                        "type": "integer",
                        "enum": [
                          86400,
                          604800,
                          2592000
                        ],
                        "description": "Obrigatório ao fixar."
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_message_id`, `from_me_required`, `sender_required`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/messages/{messageId}/star": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "messageId",
          "in": "path",
          "required": true,
          "description": "ID da mensagem no WhatsApp.",
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9]{6,128}$"
          }
        }
      ],
      "post": {
        "summary": "Favoritar mensagem",
        "operationId": "post-number-messages-messageId-star",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/MessageActionInput"
                  },
                  {
                    "type": "object",
                    "required": [
                      "star"
                    ],
                    "properties": {
                      "star": {
                        "type": "boolean"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_message_id`, `from_me_required`, `sender_required`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/communities": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Criar comunidade",
        "operationId": "post-number-communities",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "description": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 2048
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupSummary"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_group_name`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/communities/{jid}/groups": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "get": {
        "summary": "Grupos de uma comunidade",
        "operationId": "get-number-communities-jid-groups",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "jid",
                          "name",
                          "is_default_subgroup"
                        ],
                        "properties": {
                          "jid": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "is_default_subgroup": {
                            "type": "boolean"
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      },
      "post": {
        "summary": "Vincular ou desvincular grupos",
        "operationId": "post-number-communities-jid-groups",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "action",
                  "groups"
                ],
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "link",
                      "unlink"
                    ]
                  },
                  "groups": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/GroupJid"
                    },
                    "minItems": 1,
                    "maxItems": 20
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "jid",
                        "action",
                        "groups"
                      ],
                      "properties": {
                        "jid": {
                          "type": "string"
                        },
                        "action": {
                          "type": "string"
                        },
                        "groups": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "jid",
                              "ok"
                            ],
                            "properties": {
                              "jid": {
                                "type": "string"
                              },
                              "ok": {
                                "type": "boolean"
                              },
                              "error": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": false
                          }
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_groups`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Criar grupo",
        "operationId": "post-number-groups",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateGroupInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupSummary"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_group_name`, `invalid_participants`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      },
      "get": {
        "summary": "Listar grupos do número",
        "operationId": "get-number-groups",
        "description": "Uma consulta ao WhatsApp traz todos os grupos de que o número participa; a API filtra (`search`) e pagina (`limit`, `offset`) essa resposta, em ordem de nome. `data` continua sendo a lista; `total` conta os grupos depois do filtro e `next_offset` é o `offset` da próxima página (`null` na última). Cada página repete a consulta: para varrer tudo, prefira `limit=1000`. Se a resposta for 202, a lista completa (sem filtro nem ordem) fica em `/v1/operations/{id}`.\n\nEm grupos por LID (`addressing_mode: lid`) o WhatsApp pode esconder telefones: `phone` vem do próprio grupo ou do que o número já conhece (`phone_source`), e pode faltar. O telefone que o grupo esconde e só o número conhece (`phone_source: lid_map`) vem `null`, com `masked_phone`, a menos que a chave tenha o escopo `audiences:export`. `is_admin` do grupo diz se o próprio número administra o grupo.\n\nParticipantes são dados pessoais: o resultado guardado de uma consulta de grupos (repetição pela mesma `Idempotency-Key` ou `/v1/operations/{id}`) é apagado 1 hora depois; a partir daí a resposta é 410 `result_expired` e basta consultar de novo.\n\nEscopo: `engine:read`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "parameters": [
          {
            "name": "include_participants",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Parte do nome ou do JID; ignora maiúsculas e acentos. Vazio não filtra.",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 1000
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz a página de grupos.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "total",
                    "next_offset"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/GroupSummary"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "next_offset": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/invites/{code}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "code",
          "in": "path",
          "required": true,
          "description": "Código do convite ou o link completo (codificado na URL).",
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          }
        }
      ],
      "get": {
        "summary": "Ver grupo pelo convite",
        "operationId": "get-number-groups-invites-code",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupSummary"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_invite`, `invite_revoked`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/join": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Entrar em grupo por convite",
        "operationId": "post-number-groups-join",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Informe `code` **ou** `link`.",
                "properties": {
                  "code": {
                    "$ref": "#/components/schemas/GroupInviteCode"
                  },
                  "link": {
                    "$ref": "#/components/schemas/GroupInviteCode"
                  }
                },
                "additionalProperties": false,
                "oneOf": [
                  {
                    "required": [
                      "code"
                    ]
                  },
                  {
                    "required": [
                      "link"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "jid"
                      ],
                      "properties": {
                        "jid": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_invite`, `invite_revoked`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "get": {
        "summary": "Dados do grupo e participantes",
        "operationId": "get-number-groups-jid",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupSummary"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_group_jid`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}/announce": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "put": {
        "summary": "Só administradores enviam",
        "operationId": "put-number-groups-jid-announce",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "enabled"
                ],
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "jid",
                        "enabled"
                      ],
                      "properties": {
                        "jid": {
                          "type": "string"
                        },
                        "enabled": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}/description": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "put": {
        "summary": "Alterar descrição do grupo",
        "operationId": "put-number-groups-jid-description",
        "description": "Descrição vazia remove a atual.\n\nEscopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "description"
                ],
                "properties": {
                  "description": {
                    "type": "string",
                    "maxLength": 2048
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "jid",
                        "description"
                      ],
                      "properties": {
                        "jid": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_description`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}/ephemeral": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "put": {
        "summary": "Mensagens temporárias do grupo",
        "operationId": "put-number-groups-jid-ephemeral",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "seconds"
                ],
                "properties": {
                  "seconds": {
                    "type": "integer",
                    "enum": [
                      0,
                      86400,
                      604800,
                      7776000
                    ]
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "jid",
                        "seconds"
                      ],
                      "properties": {
                        "jid": {
                          "type": "string"
                        },
                        "seconds": {
                          "type": "integer"
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_ephemeral_timer`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}/image": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "put": {
        "summary": "Trocar foto do grupo",
        "operationId": "put-number-groups-jid-image",
        "description": "JPEG até 700 KiB, em base64 ou por `media_id` de uma mídia enviada antes.\n\nEscopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GroupImageInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "jid",
                        "picture_id"
                      ],
                      "properties": {
                        "jid": {
                          "type": "string"
                        },
                        "picture_id": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_image`, `image_too_large`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound",
            "description": "`not_found`, `media_not_found`."
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_image`, `media_integrity_failed`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}/invite-link": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "get": {
        "summary": "Link de convite",
        "operationId": "get-number-groups-jid-invite-link",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupInviteLink"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invite_not_allowed`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}/invite-link/reset": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "post": {
        "summary": "Gerar novo link de convite",
        "operationId": "post-number-groups-jid-invite-link-reset",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupInviteLink"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invite_not_allowed`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}/join-approval": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "put": {
        "summary": "Aprovar entrada pelo link",
        "operationId": "put-number-groups-jid-join-approval",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "enabled"
                ],
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "jid",
                        "enabled"
                      ],
                      "properties": {
                        "jid": {
                          "type": "string"
                        },
                        "enabled": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}/leave": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "post": {
        "summary": "Sair do grupo",
        "operationId": "post-number-groups-jid-leave",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "jid",
                        "left"
                      ],
                      "properties": {
                        "jid": {
                          "type": "string"
                        },
                        "left": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}/locked": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "put": {
        "summary": "Só administradores editam o grupo",
        "operationId": "put-number-groups-jid-locked",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "enabled"
                ],
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "jid",
                        "enabled"
                      ],
                      "properties": {
                        "jid": {
                          "type": "string"
                        },
                        "enabled": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}/member-add-mode": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "put": {
        "summary": "Quem pode adicionar membros",
        "operationId": "put-number-groups-jid-member-add-mode",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "mode"
                ],
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": [
                      "admins",
                      "all"
                    ]
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "jid",
                        "mode"
                      ],
                      "properties": {
                        "jid": {
                          "type": "string"
                        },
                        "mode": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_member_add_mode`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}/name": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "put": {
        "summary": "Renomear grupo",
        "operationId": "put-number-groups-jid-name",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "jid",
                        "name"
                      ],
                      "properties": {
                        "jid": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_group_name`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}/participants": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "post": {
        "summary": "Adicionar, remover, promover ou rebaixar",
        "operationId": "post-number-groups-jid-participants",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GroupParticipantsInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupParticipantsUpdate"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_action`, `invalid_participant`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}/invite-message": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "post": {
        "summary": "Enviar convite individual",
        "operationId": "post-number-groups-jid-invite-message",
        "description": "Envia o cartão \"Entrar no grupo\" numa conversa privada com quem a privacidade impediu de adicionar. Use o `add_request` (`code` e `expires_at`) que `POST …/groups/{jid}/participants` com `action: add` devolveu para **essa** pessoa neste grupo, por este número, nos últimos 8 dias: qualquer outro par telefone/código é recusado (422 `invite_not_requested`). O código só vale para ela e vence em cerca de 3 dias. Como é uma mensagem, pede o mesmo que um envio (envio liberado e vaga do número ativa: senão 503 `send_unavailable`), aceita legenda de até 200 caracteres e no máximo um convite a cada 3 segundos por número (429 `rate_limited`). Para divulgar o grupo a várias pessoas, envie o link de convite como texto.\n\nEscopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GroupInviteMessageInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Convite enviado; `data` traz a mensagem.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupInviteMessage"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo. `numbers_over_limit`: o envio da conta está pausado por ter mais números do que o plano permite."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "`invite_not_requested`: não há `add_request` registrado para essa pessoa, esse código e esse grupo. Ou a operação falhou no WhatsApp; `error.code` traz o motivo (ex.: `invite_expired`, `not_group_member`, `group_info_unavailable`)."
          },
          "429": {
            "$ref": "#/components/responses/Error",
            "description": "`rate_limited`: outro convite saiu deste número há menos de 3 segundos."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown",
            "description": "Não dá para saber se o convite saiu: confira a conversa antes de enviar de novo."
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`, `send_unavailable` (envio da conta não liberado ou vaga do número inativa)"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/groups/{jid}/requests": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/GroupJid"
          }
        }
      ],
      "get": {
        "summary": "Pedidos de entrada pendentes",
        "operationId": "get-number-groups-jid-requests",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EngineResult"
                      }
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      },
      "post": {
        "summary": "Aprovar ou recusar pedidos de entrada",
        "operationId": "post-number-groups-jid-requests",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Grupos e comunidades"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GroupRequestsInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupParticipantsUpdate"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_group_jid`, `invalid_participants`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/blocklist": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Lista de bloqueados",
        "operationId": "get-number-blocklist",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/calls": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Histórico de ligações do número",
        "operationId": "get-number-calls",
        "description": "Ligações do número, da mais nova para a mais antiga: recebidas e feitas pelo FlowZap (console ou API com áudio) e as que só tocaram no celular. `missed` marca recebidas não atendidas; `via` diz por onde foi atendida ou feita; `user_id` é a pessoa da equipe que atendeu ou ligou pelo console; `actor_label` e `ended_by_label`, o atendente do seu sistema que fez, atendeu, recusou ou desligou pela API. Cada ligação traz `recording` (metadados da gravação) quando há gravação; o áudio é baixado em `GET …/calls/{callId}/recording`.\n\n**Situação e tempos.** `state` resume a ligação (`ringing`, `answered`, `in_progress` — a voz conectou —, `completed`, `missed`, `no_answer`, `declined`, `cancelled`, `failed`, `ended`) e `ended_by` diz quem encerrou (`agent`, `contact`, `system`). `requested_at` (pedido), `started_at` (início do toque), `answered_at`, `audio_connected_at` (voz conectada) e `ended_at`, em UTC; `wait_duration_ms` é a espera e `talk_duration_ms` a conversa (`duration_ms` inclui o toque). O WhatsApp não informa \"ocupado\": um contato ocupado aparece como `declined`. Veja `Call` para a tabela completa de `reason` → `state`/`ended_by`.\n\nO histórico vem dos eventos `call.*` do número e aparece em segundos; as ligações dos últimos 90 dias anteriores a esta versão também entram.\n\nFiltros: `status` (`all`, `missed`, `answered`), `direction`, `from`/`to` (início da ligação, ISO 8601; `to` exclusivo), `phone` (E.164), `user_id`. Páginas de até 100 (`limit`, padrão 50) com `next_cursor`.\n\nEscopo: `calls:read`.",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:read"
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "missed",
                "answered"
              ],
              "default": "all"
            }
          },
          {
            "name": "direction",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "inbound",
                "outbound"
              ]
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "phone",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/E164"
            }
          },
          {
            "name": "user_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 300
            },
            "description": "Valor de `next_cursor` da página anterior."
          }
        ],
        "responses": {
          "200": {
            "description": "Uma página de ligações.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Call"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "summary": "Fazer ligação (beta)",
        "operationId": "post-number-calls",
        "description": "**Beta.** Só para números com ligações: os números escolhidos para ligações (`PUT /v1/calls/numbers`, dentro da quantidade contratada) ligam para qualquer número; sem números contratados, a liberação de teste da conta liga só para os números de teste dela (aceitos também sem o nono dígito de celular brasileiro) — fora deles, 403 `call_target_not_allowed`. Número sem ligações: 403 `calls_not_enabled`.\n\n**Sem `audio`** (ligação de teste): a resposta é 202 com o `operation_id` (uma repetição de operação já concluída devolve o resultado). Acompanhe por `GET /v1/operations/{id}`: a operação termina com sucesso, `{\"call_id\", \"status\": \"ringing\"}`, assim que a chamada é oferecida (em até 20 s); quem atende ouve um aviso de teste. A ligação continua depois disso e é informada pelos eventos `call.started`, `call.answered` e `call.ended`. Sem atender em 45 s, a ligação é cancelada.\n\n**Com `audio: true`** (ligação ao vivo, como no console): a resposta é 202 com `media_session_id` e `media` (`CallMediaStarted`). Os eventos `call.started`, `call.answered`, `call.media_connected` e `call.ended` trazem o `media_session_id`. Conecte o WebSocket de áudio (`media.url`) logo após a resposta 202, sem esperar a operação: o telefone do contato só toca depois que o áudio do atendente estiver conectado. A operação termina com sucesso, `{\"call_id\", \"status\": \"ringing\"}`, assim que a chamada é oferecida — em até 45 s no pior caso (até 20 s esperando o áudio do atendente conectar e até 20 s para oferecer a chamada). Se o áudio do atendente não conectar em 20 s, a operação falha com `media_failed` e o telefone do contato não chega a tocar (nenhum evento `call.*` é emitido).\n\n### Áudio pelo WebSocket (contrato)\n- **Conexão:** `GET` com upgrade para WebSocket em `media.url` (`wss://<host>/v1/calls/media?ticket=…`), sem cabeçalho de autenticação: o bilhete na URL é a credencial. Ele vale **60 s** para conectar e **uma única conexão**; vencido ou já usado, o hub fecha com **4001**. Antes de conectar, um bilhete novo para a mesma sessão sai em `POST …/calls/{media_session_id}/media-ticket` (ou repetindo o pedido com a mesma `Idempotency-Key`). Sem compressão (permessage-deflate desligado).\n- **Origem (navegador):** o hub aceita o próprio endereço do FlowZap, conexões sem cabeçalho `Origin` (clientes fora do navegador: servidor, app nativo) e as origens exatas cadastradas para a sua conta (`GET/POST/DELETE /v1/calls/media-origins`, escopo `calls:admin`, até 10, como `https://softphone.cliente.com.br`, sem curinga; `http://localhost[:porta]` e `http://127.0.0.1[:porta]` para desenvolvimento). A lista vai assinada dentro do bilhete: vale para os bilhetes emitidos depois da mudança. Cada conta (homologação, produção) tem a própria lista; nada muda nas outras. Uma página de outra origem chega a abrir o WebSocket, mas recebe `{\"type\":\"state\",\"state\":\"ended\",\"reason\":\"origin_not_allowed\"}` e o fechamento **4003** (`origin_not_allowed`), visíveis no seu JavaScript. O bilhete não é consumido: dentro dos 60 s, o mesmo bilhete ainda conecta a partir de uma página autorizada.\n- **Áudio:** quadros **binários** de 20 ms, PCM16 little-endian, mono, 16 kHz = **640 bytes** por quadro, nos dois sentidos. Quadros de outro tamanho são descartados; mensagem acima de 16 KiB fecha a conexão. Em atraso, o hub descarta os quadros mais novos (fila de ~1 s por lado) em vez de atrasar o outro lado.\n- **Controle:** mensagens de **texto** JSON (`CallMediaControl`): `state` (`waiting_peer`, `connected`, `ended` com `reason`), `ping` do hub a cada 10 s (não precisa responder) e `pong` em resposta ao seu `{\"type\":\"ping\"}`.\n- **Manter viva:** qualquer mensagem sua (áudio ou `{\"type\":\"ping\"}`) zera o relógio; **30 s** sem receber nada fecham a sessão (4008, `idle_timeout`). Mande áudio continuamente (silêncio também) ou um `ping` a cada 10 s.\n- **Espera pelo número:** se você conectar antes do número, a sessão espera o número por até 30 s (90 s quando o número conecta primeiro); depois, 4008 `pair_timeout`.\n- **Limites:** 10 sessões de áudio simultâneas por organização (a 11ª recebe `ended`/`org_full` e fecha com **1013**), duração máxima de **2 h** (4008 `max_duration`), uma conexão por lado (a segunda recebe **4009** `duplicate_leg` sem afetar a primeira).\n- **Códigos de fechamento:** `1000` fim normal (o outro lado saiu: `peer_left`, ou você fechou); `1001` hub em manutenção (`shutdown`); `1013` sem capacidade agora (`org_full`/`hub_full`: tente de novo em alguns segundos); `4001` bilhete inválido, vencido ou já usado (peça outro); `4003` origem da página não permitida para a conta (`origin_not_allowed`; o bilhete continua valendo); `4008` tempo esgotado (`idle_timeout`, `pair_timeout`, `max_duration`); `4009` conexão repetida para a mesma sessão. Antes de fechar depois de um bilhete válido, o hub envia `{\"type\":\"state\",\"state\":\"ended\",\"reason\":…}`.\n- **Voz conectada:** o evento `call.media_connected` (e `audio_connected_at` em `GET …/calls/{callId}`) é o sinal de que a voz está passando: o WhatsApp atendeu, o seu WebSocket estava conectado e o primeiro áudio chegou. Uma ligação sem esse evento nunca teve voz.\n- **Queda da conexão:** se o seu WebSocket cair, a ligação termina (o número desliga); não é possível reconectar o áudio a uma ligação em andamento (por exemplo, depois de recarregar a página).\n- **Limitações:** só ligações de voz individuais (sem ligações em grupo, sem vídeo, sem transferência para outro atendente ou número). Uma ligação recebida é atendida uma vez: o segundo `…/answer` para a mesma chamada recebe 409 `call_already_answering`.\n\nFalhas da operação (`error.code`, operação `failed`): `calls_not_enabled` e `call_target_not_allowed` (o número verifica de novo), `call_in_progress` (o número já está em uma ligação), `calls_unavailable` (ligações indisponíveis neste número agora), `invalid_phone`, `media_failed` (com áudio: o número não conectou o áudio; o telefone nem toca).\n\n**Aviso de gravação** (só com `audio: true`; a ligação de teste nunca é gravada, e `recording_notice` sem `audio` é 400 `invalid_input`): quando o número grava as ligações, `recording_notice: false` dispensa o aviso falado só nesta ligação — a gravação começa assim que o áudio conecta e o cliente ouve o atendente direto; `true` toca o aviso mesmo com o padrão do número desligado. Sem o campo vale `notice_default` do número (`GET …/call-recording`). Sem o aviso, a empresa precisa informar a gravação ao cliente de outra forma (LGPD).\n\n**Atendente do seu sistema** (só com `audio: true`): `actor_label` (1 a 80 caracteres, espaços nas pontas removidos) guarda quem fez a ligação, como enviado (declarado, não verificado) — as mesmas regras de `actor_label` dos atendimentos. Volta em `actor_label` de `GET …/calls/{callId}`; nunca vai para o WhatsApp. Sem `audio`, 400 `invalid_input`.\n\nUse `Idempotency-Key`: repetir com a mesma chave devolve a mesma operação e nunca faz uma segunda ligação; com áudio, a repetição traz um bilhete novo para a mesma sessão. A mesma chave com e sem `audio` (ou com outro `recording_notice` ou `actor_label`) é conteúdo diferente (409 `idempotency_conflict`).\n\nEscopo: `calls:write` (chaves criadas antes dele: `engine:write`).",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "to"
                ],
                "properties": {
                  "to": {
                    "$ref": "#/components/schemas/E164"
                  },
                  "audio": {
                    "type": "boolean",
                    "default": false,
                    "description": "true: ligação ao vivo, com o áudio pelo WebSocket de `media`."
                  },
                  "recording_notice": {
                    "type": "boolean",
                    "description": "Só com `audio: true`. Se o número grava: `false` não toca o aviso de gravação nesta ligação, `true` toca. Ausente: o `notice_default` do número."
                  },
                  "actor_label": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80,
                    "description": "Só com `audio: true`. Nome do atendente no seu sistema, guardado na ligação como enviado (declarado, não verificado)."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "to": "+5511999990000",
                "audio": true,
                "actor_label": "Ana (Gonzaga)"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Repetição sem `audio`, com a mesma `Idempotency-Key`, de uma operação já concluída; `data` traz `{\"call_id\", \"status\": \"ringing\"}`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Na fila. Sem `audio`: `{operation_id, state}`. Com `audio`: também `media_session_id` e `media` (`url`, `ticket`, `expires_at`).",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "operation_id",
                        "state"
                      ],
                      "properties": {
                        "operation_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "state": {
                          "type": "string"
                        },
                        "media_session_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Com `audio`: a sessão de áudio (igual ao `operation_id`)."
                        },
                        "media": {
                          "type": "object",
                          "required": [
                            "url",
                            "ticket",
                            "expires_at"
                          ],
                          "properties": {
                            "url": {
                              "type": "string",
                              "description": "Endereço do WebSocket, já com o bilhete."
                            },
                            "ticket": {
                              "type": "string"
                            },
                            "expires_at": {
                              "type": "string",
                              "format": "date-time",
                              "description": "Até quando o bilhete serve para conectar (60 s); a ligação pode durar mais."
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `organization_suspended`, `calls_not_enabled` (o número não tem ligações) ou `call_target_not_allowed` (só na liberação de teste: `to` não é um número de teste da conta)."
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo (inclusive outro `actor_label`); `numbers_over_limit`: envios pausados por números acima do plano."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "Repetição de uma operação que falhou; `error.code`: `calls_not_enabled`, `call_target_not_allowed`, `call_in_progress`, `calls_unavailable`, `invalid_phone` ou `media_failed`."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/calls/readiness": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Ver se o número está pronto para ligações (beta)",
        "operationId": "get-number-calls-readiness",
        "description": "**Beta.** Diagnóstico de leitura: se este número consegue fazer (`can_place`) e atender (`can_receive`) ligações agora por esta chave e, quando não, o motivo objetivo. Nunca liga, nunca consulta o celular. `mode`: `off` (sem ligações), `test_callers` (piloto: só os números de teste) ou `any_caller` (ligações contratadas).\n\n`checks`, em ordem, cada um `{name, ok, code, detail?}` (`code` só quando bloqueia; `blockers` junta esses códigos):\n- `account`: `organization_suspended`.\n- `calls_module`: `calls_not_enabled` (o número não tem ligações; escolha-o em `PUT /v1/calls/numbers`).\n- `number_connection`: `number_not_connected`.\n- `key_scope`: `scope_denied` (esta chave não tem `calls:write`, então não faz nem atende).\n- `target` (só com `to` e chave com `calls:write`; uma chave só de leitura não recebe esta checagem): `invalid_phone` ou `call_target_not_allowed` (no piloto, `to` não é número de teste; a grafia sem o nono dígito de um celular brasileiro conta como o mesmo número). Os números de teste nunca aparecem aqui.\n- `media_origins` (informativo, sempre `ok`): quantas origens de navegador a conta tem; sem nenhuma, o áudio abre no domínio do FlowZap e em clientes fora do navegador.\n- `recording` (informativo, sempre `ok`): se o número grava e se o aviso falado toca por padrão.\n\nFora deste diagnóstico, porque acontecem na ligação: microfone negado, origem recusada pelo WebSocket, bilhete vencido ou já usado, falha de mídia, ausência de áudio e a permissão do atendente. Uma chave presa a área de trabalho ou número só consulta os próprios números (404 nos demais).\n\nEscopo: `calls:read`.",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:read"
        ],
        "parameters": [
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Destino a avaliar (E.164). Inválido não é 400: aparece como `invalid_phone` em `target`.",
            "schema": {
              "type": "string",
              "maxLength": 32
            },
            "example": "+5511912345678"
          }
        ],
        "responses": {
          "200": {
            "description": "O diagnóstico.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "instance_id",
                        "mode",
                        "can_place",
                        "can_receive",
                        "checks",
                        "blockers"
                      ],
                      "properties": {
                        "instance_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "mode": {
                          "type": "string",
                          "enum": [
                            "off",
                            "test_callers",
                            "any_caller"
                          ]
                        },
                        "can_place": {
                          "type": "boolean"
                        },
                        "can_receive": {
                          "type": "boolean"
                        },
                        "checks": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "name",
                              "ok",
                              "code"
                            ],
                            "properties": {
                              "name": {
                                "type": "string",
                                "enum": [
                                  "account",
                                  "calls_module",
                                  "number_connection",
                                  "key_scope",
                                  "target",
                                  "media_origins",
                                  "recording"
                                ]
                              },
                              "ok": {
                                "type": "boolean"
                              },
                              "code": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "detail": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "blockers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "instance_id": "3f9a2c1e-6b7d-4e8f-9a0b-1c2d3e4f5a6b",
                    "mode": "test_callers",
                    "can_place": false,
                    "can_receive": true,
                    "checks": [
                      {
                        "name": "account",
                        "ok": true,
                        "code": null
                      },
                      {
                        "name": "calls_module",
                        "ok": true,
                        "code": null,
                        "detail": "Piloto: ligações só com os números de teste da conta."
                      },
                      {
                        "name": "number_connection",
                        "ok": true,
                        "code": null
                      },
                      {
                        "name": "key_scope",
                        "ok": true,
                        "code": null
                      },
                      {
                        "name": "target",
                        "ok": false,
                        "code": "call_target_not_allowed",
                        "detail": "No piloto, só os números de teste da conta recebem ligações."
                      },
                      {
                        "name": "media_origins",
                        "ok": true,
                        "code": null,
                        "detail": "2 origem(ns) de navegador cadastrada(s) para o áudio."
                      },
                      {
                        "name": "recording",
                        "ok": true,
                        "code": null,
                        "detail": "O número não grava as ligações."
                      }
                    ],
                    "blockers": [
                      "call_target_not_allowed"
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input` (parâmetro desconhecido ou repetido)"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/calls/{callId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "callId",
          "in": "path",
          "required": true,
          "description": "Id da ligação no histórico (`id`) ou o `call_id` do WhatsApp.",
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{4,128}$"
          }
        }
      ],
      "get": {
        "summary": "Ver ligação",
        "operationId": "get-number-calls-callId",
        "description": "Uma ligação do histórico, com a situação da gravação.\n\nEscopo: `calls:read`.",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:read"
        ],
        "responses": {
          "200": {
            "description": "A ligação.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Call"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/calls/{callId}/recording": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "callId",
          "in": "path",
          "required": true,
          "description": "Id da ligação no histórico (`id`) ou o `call_id` do WhatsApp.",
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{4,128}$"
          }
        }
      ],
      "get": {
        "summary": "Baixar gravação da ligação",
        "operationId": "get-number-calls-callId-recording",
        "description": "O áudio da ligação: Ogg/Opus estéreo, 16 kHz — canal esquerdo, a outra pessoa; canal direito, o que ela ouviu (o aviso de gravação e a equipe). Aceita `Range` (206 com `Content-Range`), para tocar e avançar sem baixar tudo; nunca vai para cache. Cada resposta com áudio (200 ou 206) é registrada (quem, quando, por qual chave), uma vez a cada 5 minutos por chave e gravação. `HEAD` responde só os cabeçalhos (tamanho em `Content-Length`), sem registro.\n\nO arquivo é `audio/ogg; codecs=opus`, 2 canais, 16 kHz (`recording.mime`, `channels`, `sample_rate_hz`).\n\nDisponível enquanto a gravação está guardada: 7 dias sem o módulo Gravações no FlowZap; o prazo escolhido (até 90 dias) com ele. Sem arquivo, 404 `recording_not_found` com `reason`: `not_recorded` (a ligação não foi gravada: sem áudio pelo FlowZap, gravação desligada ou espaço esgotado — veja `recording_state`), `failed` (a gravação falhou: `recording.failure_reason`), `expired` (o prazo acabou) ou `deleted` (apagada por alguém). Ainda gravando ou em conversão (segundos depois do fim), 409 `recording_not_ready` com `recording_state` (`recording` ou `processing`) — espere o webhook `call.recording_ready` (ou `call.recording_failed`).\n\nEscopo: `calls:recordings` (à parte de `calls:read`: listar ligações não dá acesso ao áudio).",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:recordings"
        ],
        "parameters": [
          {
            "name": "Range",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "example": "bytes=0-"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "O arquivo inteiro (`audio/ogg`, `Content-Disposition: attachment`).",
            "content": {
              "audio/ogg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "206": {
            "description": "O trecho pedido em `Range`.",
            "content": {
              "audio/ogg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "description": "`not_found` (ligação) ou `recording_not_found` com `reason`: `not_recorded`, `failed`, `expired` ou `deleted`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "recording_not_found",
                    "message": "recording_not_found",
                    "request_id": "0b5e3c8a-1f2d-4c6b-9a77-2f4f0e6d9c11",
                    "retryable": false,
                    "reason": "expired"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`recording_not_ready` com `recording_state`: `recording` (a ligação ainda grava) ou `processing` (em conversão).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "recording_not_ready",
                    "message": "recording_not_ready",
                    "request_id": "0b5e3c8a-1f2d-4c6b-9a77-2f4f0e6d9c11",
                    "retryable": false,
                    "recording_state": "processing"
                  }
                }
              }
            }
          },
          "416": {
            "description": "`Range` fora do arquivo (`Content-Range: bytes */<tamanho>`)."
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`recordings_unavailable`, `recordings_busy`, `recording_unavailable` (tente de novo em instantes)."
          }
        }
      },
      "delete": {
        "summary": "Apagar gravação da ligação",
        "operationId": "delete-number-calls-callId-recording",
        "description": "Apaga a gravação agora (o arquivo deixa de ser servido na hora e é removido do disco em segundos); a ligação continua no histórico com `recording.state: deleted` e `recording.deleted_reason: api`. Repetir devolve a mesma resposta. Gera o webhook `call.recording_deleted`. A exclusão é registrada (quem, quando, por qual chave).\n\nEscopos: `calls:write` e `calls:recordings`.",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:write",
          "calls:recordings"
        ],
        "responses": {
          "200": {
            "description": "Gravação apagada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "call_id",
                        "recording_id",
                        "state",
                        "deleted_at"
                      ],
                      "properties": {
                        "call_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Id da ligação no histórico."
                        },
                        "recording_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "deleted"
                          ]
                        },
                        "deleted_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/Error",
            "description": "`not_found`, `recording_not_found` (com `reason: not_recorded`)"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/call-recording": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Ver gravação das ligações do número",
        "operationId": "get-number-call-recording",
        "description": "Se o número grava as ligações, por quantos dias guarda, se tem o módulo Gravações no FlowZap, o texto do aviso e o espaço usado pela conta.\n\nEscopo: `calls:read`.",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:read"
        ],
        "responses": {
          "200": {
            "description": "A configuração do número.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CallRecordingPolicy"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "summary": "Ligar ou desligar a gravação das ligações",
        "operationId": "put-number-call-recording",
        "description": "Liga ou desliga a gravação das ligações do número (desligada por padrão). Só são gravadas as ligações que passam pelo FlowZap com áudio (console ou API com `audio: true`); atendidas no celular e ligações de teste nunca. Repetir os mesmos valores não muda nada.\n\n**Aviso e LGPD.** Com a gravação ligada, cada ligação começa com o aviso falado \"Esta ligação pode ser gravada para fins de qualidade e segurança.\", ouvido pelos dois lados, e a gravação começa nele. `notice_default: false` (só o proprietário, um administrador ou uma chave com `calls:write`) faz as ligações gravadas começarem sem o aviso, a não ser que a própria ligação peça (`recording_notice: true` em `POST …/calls` com `audio` ou em `…/answer`); cada ligação também pode dispensá-lo (`recording_notice: false`). Sem o aviso, a empresa precisa informar a gravação ao cliente de outra forma. A gravação feita sem aviso por escolha fica guardada e aparece com `recording.notice_mode: skipped_by_choice`; quem escolheu é a pessoa da ligação (`user_id`) ou a chave da API (`via: api`). A conta é a controladora desses dados: cabe a ela ter base legal para gravar (por exemplo, legítimo interesse ou consentimento), informar a finalidade na sua política de privacidade e atender os pedidos dos titulares (acesso e exclusão: `GET` e `DELETE …/calls/{callId}/recording`). O FlowZap guarda o áudio cifrado, fora do banco e dos backups, apaga-o sozinho no fim do prazo e registra cada acesso.\n\n**Prazo.** Sem o módulo Gravações no FlowZap, 7 dias (o áudio fica disponível só pela API, MCP e webhook). Com o módulo, `retention_days` de 7 a 90 (padrão 90), e o console ganha ouvir e baixar. `retention_days` acima de 7 sem o módulo: 403 `recording_module_required`. O prazo vale para as gravações novas; um prazo menor encurta também as já guardadas (nunca alonga). Sem o módulo (ou quando ele sai do número), as gravações guardadas ficam 7 dias a partir de quando ficaram prontas, e `retention_until` mostra isso.\n\n**Gravação descartada.** Se a pessoa desliga antes do fim de um aviso que devia tocar, a gravação é descartada na hora (`state: failed`, `notice_mode: incomplete`, sem arquivo): sem o aviso inteiro nada fica guardado. Uma gravação vai no máximo até 2 horas; a ligação segue sem gravar depois disso.\n\n**Espaço.** 10 GiB por conta; no limite, as ligações seguem sem gravar (`recording_state: skipped_quota`).\n\nEscopo: `calls:write`.",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CallRecordingPolicyInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A configuração gravada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CallRecordingPolicy"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `organization_suspended`, `recording_module_required`"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/calls/{callId}/answer": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "callId",
          "in": "path",
          "required": true,
          "description": "ID da chamada, do evento `call.ringing`.",
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{4,128}$"
          }
        }
      ],
      "post": {
        "summary": "Atender ligação (beta)",
        "operationId": "post-number-calls-callId-answer",
        "description": "**Beta.** Atende uma ligação que está tocando neste número (evento `call.ringing` sem `call.ended`); fora disso, 409 `call_not_ringing`. A resposta é 202 com `media_session_id` e `media`: conecte o áudio pelo WebSocket como em `POST …/calls` com `audio` (contrato completo lá: PCM16 mono 16 kHz, quadros de 20 ms / 640 bytes, nos dois sentidos, bilhete de 60 s e uso único). Mesmas regras de ligações do número.\n\n**Um atendimento por ligação:** se outra pessoa (pelo console ou por outra chave) já atendeu esta chamada — atendimento na fila, em andamento ou concluído nos últimos 5 minutos —, a resposta é 409 `call_already_answering` na hora, sem criar operação. Repetir o seu próprio pedido com a mesma `Idempotency-Key` continua devolvendo a sua operação. Se o atendimento anterior falhou ou venceu, um novo `…/answer` é aceito.\n\n**O atendimento espera o seu áudio:** a ligação só é atendida no WhatsApp depois que o seu WebSocket conecta em `media.url`; até lá ela continua tocando para quem ligou. Sem conexão em 20 s, a ligação termina com `reason: media_failed` sem ter sido atendida (`answered: false`). O evento `call.media_connected` é o sinal de que a voz está passando.\n\nCorpo vazio (`{}`) ou `{\"recording_notice\": false}`: quando o número grava, dispensa o aviso falado só nesta ligação (`true` toca mesmo com o padrão do número desligado; ausente, vale o `notice_default` do número). `actor_label` (1 a 80 caracteres) guarda o atendente do seu sistema que atendeu, como enviado (declarado, não verificado); volta em `actor_label` da ligação. `Idempotency-Key` obrigatória; a repetição traz um bilhete novo para a mesma sessão; a mesma chave com outro `recording_notice` ou `actor_label` é 409 `idempotency_conflict`.\n\nEscopo: `calls:write` (chaves criadas antes dele: `engine:write`).",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "recording_notice": {
                    "type": "boolean",
                    "description": "Se o número grava: `false` não toca o aviso de gravação nesta ligação, `true` toca. Ausente: o `notice_default` do número."
                  },
                  "actor_label": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80,
                    "description": "Nome do atendente no seu sistema, guardado na ligação como enviado (declarado, não verificado)."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "recording_notice": false,
                "actor_label": "Ana (Gonzaga)"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Na fila: `{operation_id, state, media_session_id, media: {url, ticket, expires_at}}`. Conecte o áudio em `media.url` em até 60 s.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallMediaStarted"
                },
                "example": {
                  "data": {
                    "operation_id": "6a1f0c52-8d3e-4b7a-9f21-3c5d7e9a0b14",
                    "state": "queued",
                    "media_session_id": "6a1f0c52-8d3e-4b7a-9f21-3c5d7e9a0b14",
                    "media": {
                      "url": "wss://flowzap.flowpost.com.br/v1/calls/media?ticket=v1.eyJ2IjoxLCJqdGkiOiJ...",
                      "ticket": "v1.eyJ2IjoxLCJqdGkiOiJ...",
                      "expires_at": "2026-10-30T14:02:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `idempotency_key_required`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `organization_suspended`, `calls_not_enabled`"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "`call_already_answering`: outra pessoa já atendeu esta chamada (atendimento na fila, em andamento ou concluído); `call_not_ringing`: a chamada não está tocando; `idempotency_conflict`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "call_already_answering",
                    "message": "call_already_answering",
                    "request_id": "0b5e3c8a-1f2d-4c6b-9a77-2f4f0e6d9c11",
                    "retryable": false
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed"
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/calls/{callId}/decline": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "callId",
          "in": "path",
          "required": true,
          "description": "ID da chamada, do evento `call.ringing`.",
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{4,128}$"
          }
        }
      ],
      "post": {
        "summary": "Recusar ligação que está tocando (beta)",
        "operationId": "post-number-calls-callId-decline",
        "description": "**Beta.** Recusa uma ligação que está tocando neste número à espera de atendimento (`call.ringing`); fora disso, 409 `call_not_ringing`. Corpo vazio (`{}`) ou `{\"actor_label\": \"…\"}`: o atendente do seu sistema que recusou, guardado na ligação (`ended_by_label`, com `state: declined` e `ended_by: agent`). Espera até 15 s pelo número, como as outras operações. `Idempotency-Key` obrigatória; a mesma chave com outro `actor_label` é 409 `idempotency_conflict`.\n\nEscopo: `calls:write` (chaves criadas antes dele: `engine:write`).",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "actor_label": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80,
                    "description": "Nome do atendente no seu sistema, guardado na ligação como enviado (declarado, não verificado)."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "actor_label": "Ana (Gonzaga)"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                },
                "example": {
                  "data": {
                    "call_id": "ACB1F2E3D4C5B6A7",
                    "status": "declined"
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `idempotency_key_required`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `organization_suspended`, `calls_not_enabled`"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`call_not_ringing`, `idempotency_conflict`"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed"
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/calls/{callId}/hangup": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "callId",
          "in": "path",
          "required": true,
          "description": "ID da chamada (`call.started`, `call.ringing` ou o resultado de `POST …/calls`).",
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{4,128}$"
          }
        }
      ],
      "post": {
        "summary": "Desligar ligação (beta)",
        "operationId": "post-number-calls-callId-hangup",
        "description": "**Beta.** Encerra uma ligação do número em andamento. Corpo vazio (`{}`) ou `{\"actor_label\": \"…\"}`: o atendente do seu sistema que desligou, guardado na ligação (`ended_by_label`, com `ended_by: agent`). Espera até 15 s pelo número. `Idempotency-Key` obrigatória; a mesma chave com outro `actor_label` é 409 `idempotency_conflict`.\n\nEscopo: `calls:write` (chaves criadas antes dele: `engine:write`).",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "actor_label": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80,
                    "description": "Nome do atendente no seu sistema, guardado na ligação como enviado (declarado, não verificado)."
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "actor_label": "Ana (Gonzaga)"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                },
                "example": {
                  "data": {
                    "call_id": "ACB1F2E3D4C5B6A7",
                    "status": "ending"
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `idempotency_key_required`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `organization_suspended`, `calls_not_enabled`"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed"
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/calls/{callId}/mute": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "callId",
          "in": "path",
          "required": true,
          "description": "ID da chamada em andamento.",
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{4,128}$"
          }
        }
      ],
      "post": {
        "summary": "Silenciar ou reativar o áudio enviado (beta)",
        "operationId": "post-number-calls-callId-mute",
        "description": "**Beta.** `{\"muted\": true}` para de enviar o seu áudio a quem está na ligação; `false` volta a enviar. Espera até 15 s pelo número. `Idempotency-Key` obrigatória.\n\nEscopo: `calls:write` (chaves criadas antes dele: `engine:write`).",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "muted"
                ],
                "properties": {
                  "muted": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "muted": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                },
                "example": {
                  "data": {
                    "call_id": "ACB1F2E3D4C5B6A7",
                    "muted": true
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `idempotency_key_required`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `organization_suspended`, `calls_not_enabled`"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed"
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/calls/{callId}/media-ticket": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "callId",
          "in": "path",
          "required": true,
          "description": "ID da chamada ou o `media_session_id` devolvido por `POST …/calls` (com `audio`) ou `…/answer`.",
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{4,128}$"
          }
        }
      ],
      "post": {
        "summary": "Novo bilhete de áudio (beta)",
        "operationId": "post-number-calls-callId-media-ticket",
        "description": "**Beta.** Emite um bilhete novo (60 s, uma conexão) para a sessão de áudio de uma ligação deste número aberta nas últimas 2 horas e ainda não encerrada, quando o bilhete anterior venceu antes de conectar. Não reabre uma sessão: se a conexão de áudio caiu, a ligação já terminou. Ligação encerrada (`call.ended`): 409 `call_ended`. Corpo vazio (`{}`); não cria operação.\n\nEscopo: `calls:write` (chaves criadas antes dele: `engine:write`).",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:write"
        ],
        "responses": {
          "200": {
            "description": "`{media_session_id, call_id, media: {url, ticket, expires_at}}`; `call_id` é `null` enquanto o WhatsApp não o informou.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "media_session_id",
                        "call_id",
                        "media"
                      ],
                      "properties": {
                        "media_session_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "call_id": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "media": {
                          "type": "object",
                          "required": [
                            "url",
                            "ticket",
                            "expires_at"
                          ],
                          "properties": {
                            "url": {
                              "type": "string"
                            },
                            "ticket": {
                              "type": "string"
                            },
                            "expires_at": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "media_session_id": "6a1f0c52-8d3e-4b7a-9f21-3c5d7e9a0b14",
                    "call_id": "ACB1F2E3D4C5B6A7",
                    "media": {
                      "url": "wss://flowzap.flowpost.com.br/v1/calls/media?ticket=v1.eyJ2IjoxLCJqdGkiOiJ...",
                      "ticket": "v1.eyJ2IjoxLCJqdGkiOiJ...",
                      "expires_at": "2026-10-30T14:03:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`call_ended`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/calls/{callId}/reject": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "callId",
          "in": "path",
          "required": true,
          "description": "ID da chamada, do evento `call.offer`.",
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{4,128}$"
          }
        }
      ],
      "post": {
        "summary": "Recusar chamada recebida no celular",
        "operationId": "post-number-calls-callId-reject",
        "description": "Recusa uma chamada que toca no celular do número (evento `call.offer`), sem o módulo de ligações. Use o `callId` e o `from` do evento. Para uma ligação que toca à espera de atendimento (`call.ringing`), use `…/decline`.\n\nEscopo: `calls:write` (chaves criadas antes dele: `engine:write`).",
        "tags": [
          "Ligações"
        ],
        "x-scopes": [
          "calls:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "from"
                ],
                "properties": {
                  "from": {
                    "$ref": "#/components/schemas/UserJid"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_call_id`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/conversations/links": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Juntar uma conversa sem telefone a um telefone",
        "operationId": "post-number-conversations-links",
        "description": "Algumas pessoas aparecem no WhatsApp sem o telefone (JID `@lid`), e as mensagens delas ficam numa conversa à parte. Este vínculo, o mesmo do console, junta essa conversa ao telefone informado. Vale só para este número, fica cifrado e pode ser desfeito. A conversa `@lid` precisa existir no histórico do número (senão 404 `conversation_not_found`).\n\nQuem faz o vínculo é a pessoa que criou a chave: ela precisa operar este número no console (dona, administradora, desenvolvedora ou operadora da organização ou desta área de trabalho), senão 403 `operator_required`. O histórico registra essa pessoa e a chave.\n\nRepetir o mesmo vínculo (mesmo `lid_jid`, `phone` e `name`) responde 200 com o mesmo `id` e `Idempotent-Replay: true`; o `lid_jid` já ligado a outro telefone ou nome responde 409 `contact_already_linked` (desfaça antes).\n\nEscopo: `messages:send`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Opcional (letras, números, `_ . : -`, até 128). O vínculo já é idempotente pelo conteúdo.",
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_.:-]{1,128}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "lid_jid",
                  "phone",
                  "name",
                  "confirmed"
                ],
                "additionalProperties": false,
                "properties": {
                  "lid_jid": {
                    "type": "string",
                    "pattern": "^\\d{1,20}@lid$",
                    "description": "A conversa sem telefone, como aparece em `GET …/chats`."
                  },
                  "phone": {
                    "type": "string",
                    "pattern": "^\\+[1-9]\\d{7,14}$",
                    "description": "Telefone com DDI, ex.: `+5511999999999`."
                  },
                  "name": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 160
                  },
                  "confirmed": {
                    "type": "boolean",
                    "enum": [
                      true
                    ],
                    "description": "Confirma que o telefone é dessa pessoa (vínculo errado mistura conversas)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "O mesmo vínculo já existia.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "id"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Vínculo criado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "id"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `operator_required`, `organization_suspended`"
          },
          "404": {
            "$ref": "#/components/responses/Error",
            "description": "`not_found`, `conversation_not_found`"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`contact_already_linked`"
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/conversations/links/{linkId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "linkId",
          "in": "path",
          "required": true,
          "description": "O `id` devolvido ao criar o vínculo.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "delete": {
        "summary": "Desfazer o vínculo de uma conversa",
        "operationId": "delete-number-conversations-links-linkId",
        "description": "A conversa `@lid` volta a aparecer separada. Mesma regra de quem age do vínculo: a pessoa que criou a chave, operando este número. Repetir depois de desfeito responde 404 `contact_link_not_found`.\n\nEscopo: `messages:send`.",
        "tags": [
          "Conversas e etiquetas"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "responses": {
          "204": {
            "description": "Desfeito, sem corpo."
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`, `operator_required`, `organization_suspended`"
          },
          "404": {
            "$ref": "#/components/responses/Error",
            "description": "`not_found`, `contact_link_not_found`"
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/contacts": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Listar contatos da agenda",
        "operationId": "get-number-contacts",
        "description": "`name` junta os nomes que o WhatsApp conhece (agenda do celular, senão o nome que a pessoa escolheu, senão o nome comercial); `agenda_name`, `push_name` e `business_name` trazem cada um separado e `name_source` diz de onde veio `name`.\n\nEscopo: `engine:read`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "items",
                        "total",
                        "limit",
                        "offset"
                      ],
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "jid",
                              "phone",
                              "name",
                              "agenda_name",
                              "push_name",
                              "business_name",
                              "name_source"
                            ],
                            "properties": {
                              "jid": {
                                "type": "string",
                                "description": "JID de pessoa (telefone ou `@lid`)."
                              },
                              "phone": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Telefone E.164; nulo para um `@lid`."
                              },
                              "name": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "O primeiro que existir: `agenda_name`, `push_name`, `business_name`."
                              },
                              "agenda_name": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Nome salvo na agenda do celular do número (nome completo, senão o primeiro nome)."
                              },
                              "push_name": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Nome que a pessoa escolheu no próprio WhatsApp."
                              },
                              "business_name": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Nome comercial (WhatsApp Business)."
                              },
                              "name_source": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "enum": [
                                  "agenda",
                                  "push",
                                  "business",
                                  null
                                ],
                                "description": "De onde veio `name`; nulo quando não há nome."
                              }
                            }
                          }
                        },
                        "total": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      },
      "post": {
        "summary": "Adicionar contato à agenda",
        "operationId": "post-number-contacts",
        "description": "**Não suportado pelo motor do WhatsApp usado hoje.** O WhatsApp Web não oferece gravar contatos na agenda do celular. A rota existe, autentica e responde 501 `not_supported_by_engine` (não adianta repetir).\n\nEscopo: `engine:write`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "x-status": "not_supported",
        "responses": {
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "501": {
            "$ref": "#/components/responses/NotSupported"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/contacts/check": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Verificar se telefones têm WhatsApp",
        "operationId": "post-number-contacts-check",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "phones"
                ],
                "properties": {
                  "phones": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/E164"
                    },
                    "minItems": 1,
                    "maxItems": 50
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ContactCheckResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_phone`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/contacts/{jid}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/UserJid"
          }
        }
      ],
      "delete": {
        "summary": "Remover contato da agenda",
        "operationId": "delete-number-contacts-jid",
        "description": "**Não suportado pelo motor do WhatsApp usado hoje.** O WhatsApp Web não oferece apagar contatos da agenda do celular. A rota existe, autentica e responde 501 `not_supported_by_engine` (não adianta repetir).\n\nEscopo: `engine:write`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "x-status": "not_supported",
        "responses": {
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "501": {
            "$ref": "#/components/responses/NotSupported"
          }
        }
      },
      "get": {
        "summary": "Dados de um contato",
        "operationId": "get-number-contacts-jid",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_jid`, `not_on_whatsapp`, `rate_limited`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/contacts/{jid}/avatar": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID de pessoa ou, só nesta rota, de grupo (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UserJid"
              },
              {
                "$ref": "#/components/schemas/GroupJid"
              }
            ]
          }
        }
      ],
      "get": {
        "summary": "Foto de perfil de um contato ou grupo",
        "operationId": "get-number-contacts-jid-avatar",
        "description": "Com um JID de grupo (`...@g.us`), devolve a foto do grupo no mesmo formato. `data` é `{url, id, type}`, ou `null` quando a foto está oculta pela privacidade ou não existe.\n\nEscopo: `engine:read`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "parameters": [
          {
            "name": "preview",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            },
            "description": "`true` devolve a miniatura."
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `picture_not_set`, `privacy_hidden`, `not_authorized`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/contacts/{jid}/block": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/UserJid"
          }
        }
      ],
      "post": {
        "summary": "Bloquear ou desbloquear",
        "operationId": "post-number-contacts-jid-block",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "block"
                ],
                "properties": {
                  "block": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_jid`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/presence": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Ficar online ou offline",
        "operationId": "post-number-presence",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "state"
                ],
                "properties": {
                  "state": {
                    "type": "string",
                    "enum": [
                      "available",
                      "unavailable"
                    ]
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/presence/chat": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Mostrar digitando ou gravando",
        "operationId": "post-number-presence-chat",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "to",
                  "state"
                ],
                "properties": {
                  "to": {
                    "oneOf": [
                      {
                        "$ref": "#/components/schemas/E164"
                      },
                      {
                        "$ref": "#/components/schemas/UserJid"
                      },
                      {
                        "$ref": "#/components/schemas/GroupJid"
                      }
                    ]
                  },
                  "state": {
                    "type": "string",
                    "enum": [
                      "composing",
                      "recording",
                      "paused"
                    ]
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/presence/subscribe": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Acompanhar presença de um contato",
        "operationId": "post-number-presence-subscribe",
        "description": "As mudanças chegam como evento `presence.update`.\n\nEscopo: `engine:write`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jid"
                ],
                "properties": {
                  "jid": {
                    "$ref": "#/components/schemas/UserJid"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `privacy_token_missing`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/privacy": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Ler configurações de privacidade",
        "operationId": "get-number-privacy",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      },
      "put": {
        "summary": "Alterar uma configuração de privacidade",
        "operationId": "put-number-privacy",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PrivacyInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_privacy_value`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/profile": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Perfil do próprio número",
        "operationId": "get-number-profile",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/profile/image": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "put": {
        "summary": "Trocar foto de perfil",
        "operationId": "put-number-profile-image",
        "description": "JPEG até 700 KiB, em base64 (`image`) ou por `media_id`.\n\nEscopo: `engine:write`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "required": [
                      "image"
                    ],
                    "properties": {
                      "image": {
                        "type": "string",
                        "format": "byte",
                        "maxLength": 955736
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "required": [
                      "media_id"
                    ],
                    "properties": {
                      "media_id": {
                        "type": "string",
                        "format": "uuid"
                      }
                    },
                    "additionalProperties": false
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_image`, `image_too_large`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound",
            "description": "`not_found`, `media_not_found`."
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_image`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/profile/name": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "put": {
        "summary": "Alterar nome de exibição",
        "operationId": "put-number-profile-name",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 25
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `push_name_missing`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/profile/status": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "put": {
        "summary": "Alterar recado (sobre)",
        "operationId": "put-number-profile-status",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Contatos e perfil"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 139
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/newsletters": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Criar canal",
        "operationId": "post-number-newsletters",
        "description": "Foto opcional: JPEG em base64 (`picture`) ou `media_id` — não os dois.\n\nEscopo: `engine:write`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 2048
                  },
                  "picture": {
                    "type": "string",
                    "format": "byte",
                    "maxLength": 955736
                  },
                  "media_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/NewsletterSummary"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_image`, `image_too_large`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound",
            "description": "`not_found`, `media_not_found`."
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_newsletter_name`, `invalid_image`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      },
      "get": {
        "summary": "Canais que o número segue",
        "operationId": "get-number-newsletters",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NewsletterSummary"
                      }
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/newsletters/invites/{code}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "code",
          "in": "path",
          "required": true,
          "description": "Código do convite ou o link completo (codificado na URL).",
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          }
        }
      ],
      "get": {
        "summary": "Ver canal pelo convite",
        "operationId": "get-number-newsletters-invites-code",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/NewsletterSummary"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_invite`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/newsletters/search": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Pesquisar canais públicos",
        "operationId": "get-number-newsletters-search",
        "description": "**Não suportado pelo motor do WhatsApp usado hoje.** O WhatsApp Web não expõe a pesquisa do diretório de canais. A rota existe, autentica e responde 501 `not_supported_by_engine` (não adianta repetir).\n\nEscopo: `engine:read`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "x-status": "not_supported",
        "responses": {
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "501": {
            "$ref": "#/components/responses/NotSupported"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/newsletters/{jid}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/NewsletterJid"
          }
        }
      ],
      "get": {
        "summary": "Dados do canal",
        "operationId": "get-number-newsletters-jid",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/NewsletterSummary"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_newsletter_jid`, `newsletter_not_found`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/newsletters/{jid}/admins": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/NewsletterJid"
          }
        }
      ],
      "post": {
        "summary": "Convidar administrador do canal",
        "operationId": "post-number-newsletters-jid-admins",
        "description": "**Não suportado pelo motor do WhatsApp usado hoje.** O WhatsApp Web não oferece administrar canais. A rota existe, autentica e responde 501 `not_supported_by_engine` (não adianta repetir).\n\nEscopo: `engine:write`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "x-status": "not_supported",
        "responses": {
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "501": {
            "$ref": "#/components/responses/NotSupported"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/newsletters/{jid}/follow": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/NewsletterJid"
          }
        }
      ],
      "post": {
        "summary": "Seguir ou deixar de seguir",
        "operationId": "post-number-newsletters-jid-follow",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "follow"
                ],
                "properties": {
                  "follow": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_newsletter_jid`, `newsletter_not_found`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/newsletters/{jid}/live": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/NewsletterJid"
          }
        }
      ],
      "post": {
        "summary": "Receber novidades ao vivo",
        "operationId": "post-number-newsletters-jid-live",
        "description": "As mudanças chegam como evento `newsletter.live_update`.\n\nEscopo: `engine:write`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_newsletter_jid`, `newsletter_not_found`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/newsletters/{jid}/messages": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/NewsletterJid"
          }
        }
      ],
      "get": {
        "summary": "Publicações do canal",
        "operationId": "get-number-newsletters-jid-messages",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "parameters": [
          {
            "name": "count",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^\\d{1,12}$"
            },
            "description": "1 a 100."
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^\\d{1,12}$"
            },
            "description": "Só publicações com `server_id` menor."
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NewsletterMessage"
                      }
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_newsletter_jid`, `newsletter_not_found`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/newsletters/{jid}/mute": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/NewsletterJid"
          }
        }
      ],
      "post": {
        "summary": "Silenciar canal",
        "operationId": "post-number-newsletters-jid-mute",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "mute"
                ],
                "properties": {
                  "mute": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_newsletter_jid`, `newsletter_not_found`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/newsletters/{jid}/posts": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/NewsletterJid"
          }
        }
      ],
      "post": {
        "summary": "Publicar texto no canal",
        "operationId": "post-number-newsletters-jid-posts",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 4096
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/NewsletterPostResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo. `numbers_over_limit`: o envio da conta está pausado por ter mais números do que o plano permite; repetir uma publicação já aceita devolve o mesmo resultado."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_text`, `invalid_newsletter_jid`, `newsletter_not_found`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/newsletters/{jid}/posts/{serverId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/NewsletterJid"
          }
        },
        {
          "name": "serverId",
          "in": "path",
          "required": true,
          "description": "`server_id` da publicação.",
          "schema": {
            "type": "string",
            "pattern": "^\\d{1,12}$"
          }
        }
      ],
      "put": {
        "summary": "Editar publicação",
        "operationId": "put-number-newsletters-jid-posts-serverId",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 4096
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/NewsletterPostResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo. `numbers_over_limit`: o envio da conta está pausado por ter mais números do que o plano permite; apagar a publicação continua aceito."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `post_not_found`, `post_lookup_failed`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      },
      "delete": {
        "summary": "Apagar publicação",
        "operationId": "delete-number-newsletters-jid-posts-serverId",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `post_not_found`, `post_lookup_failed`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/newsletters/{jid}/reaction": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/NewsletterJid"
          }
        }
      ],
      "post": {
        "summary": "Reagir a uma publicação",
        "operationId": "post-number-newsletters-jid-reaction",
        "description": "Reação vazia remove a anterior.\n\nEscopo: `engine:write`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "server_id",
                  "reaction"
                ],
                "properties": {
                  "server_id": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "reaction": {
                    "type": "string",
                    "maxLength": 16
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo. `numbers_over_limit`: o envio da conta está pausado por ter mais números do que o plano permite; reação vazia (remover) continua aceita."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_reaction`, `post_not_found`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/newsletters/{jid}/updates": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/NewsletterJid"
          }
        }
      ],
      "get": {
        "summary": "Novidades (visualizações e reações)",
        "operationId": "get-number-newsletters-jid-updates",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "parameters": [
          {
            "name": "count",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^\\d{1,12}$"
            },
            "description": "1 a 100."
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NewsletterMessage"
                      }
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_newsletter_jid`, `newsletter_not_found`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/newsletters/{jid}/viewed": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/NewsletterJid"
          }
        }
      ],
      "post": {
        "summary": "Marcar publicações como vistas",
        "operationId": "post-number-newsletters-jid-viewed",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Canais"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "server_ids"
                ],
                "properties": {
                  "server_ids": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "minItems": 1,
                    "maxItems": 100
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngineResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a mesma `Idempotency-Key` já foi usada com outro conteúdo."
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_server_ids`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/business/catalog": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Listar catálogo",
        "operationId": "get-number-business-catalog",
        "description": "**Não suportado pelo motor do WhatsApp usado hoje.** O catálogo não está disponível no WhatsApp Web. A rota existe, autentica e responde 501 `not_supported_by_engine` (não adianta repetir).\n\nEscopo: `engine:read`.",
        "tags": [
          "Perfil comercial"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "x-status": "not_supported",
        "responses": {
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "501": {
            "$ref": "#/components/responses/NotSupported"
          }
        }
      },
      "post": {
        "summary": "Criar produto",
        "operationId": "post-number-business-catalog",
        "description": "**Não suportado pelo motor do WhatsApp usado hoje.** O catálogo não está disponível no WhatsApp Web. A rota existe, autentica e responde 501 `not_supported_by_engine` (não adianta repetir).\n\nEscopo: `engine:write`.",
        "tags": [
          "Perfil comercial"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "x-status": "not_supported",
        "responses": {
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "501": {
            "$ref": "#/components/responses/NotSupported"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/business/catalog/{productId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "productId",
          "in": "path",
          "required": true,
          "description": "ID do produto.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "Ler produto",
        "operationId": "get-number-business-catalog-productId",
        "description": "**Não suportado pelo motor do WhatsApp usado hoje.** O catálogo não está disponível no WhatsApp Web. A rota existe, autentica e responde 501 `not_supported_by_engine` (não adianta repetir).\n\nEscopo: `engine:read`.",
        "tags": [
          "Perfil comercial"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "x-status": "not_supported",
        "responses": {
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "501": {
            "$ref": "#/components/responses/NotSupported"
          }
        }
      },
      "put": {
        "summary": "Editar produto",
        "operationId": "put-number-business-catalog-productId",
        "description": "**Não suportado pelo motor do WhatsApp usado hoje.** O catálogo não está disponível no WhatsApp Web. A rota existe, autentica e responde 501 `not_supported_by_engine` (não adianta repetir).\n\nEscopo: `engine:write`.",
        "tags": [
          "Perfil comercial"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "x-status": "not_supported",
        "responses": {
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "501": {
            "$ref": "#/components/responses/NotSupported"
          }
        }
      },
      "delete": {
        "summary": "Apagar produto",
        "operationId": "delete-number-business-catalog-productId",
        "description": "**Não suportado pelo motor do WhatsApp usado hoje.** O catálogo não está disponível no WhatsApp Web. A rota existe, autentica e responde 501 `not_supported_by_engine` (não adianta repetir).\n\nEscopo: `engine:write`.",
        "tags": [
          "Perfil comercial"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "x-status": "not_supported",
        "responses": {
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "501": {
            "$ref": "#/components/responses/NotSupported"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/business/profile": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "put": {
        "summary": "Editar perfil comercial",
        "operationId": "put-number-business-profile",
        "description": "**Não suportado pelo motor do WhatsApp usado hoje.** O WhatsApp Web só lê perfis comerciais. A rota existe, autentica e responde 501 `not_supported_by_engine` (não adianta repetir).\n\nEscopo: `engine:write`.",
        "tags": [
          "Perfil comercial"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "x-status": "not_supported",
        "responses": {
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "501": {
            "$ref": "#/components/responses/NotSupported"
          }
        }
      },
      "get": {
        "summary": "Perfil comercial do próprio número",
        "operationId": "get-number-business-profile",
        "description": "Conta pessoal responde 200 com `data: null`.\n\nEscopo: `engine:read`.",
        "tags": [
          "Perfil comercial"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/BusinessProfile"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `not_allowed`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/business/profile/{jid}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "jid",
          "in": "path",
          "required": true,
          "description": "JID (codifique `@` como `%40` se o seu cliente exigir).",
          "schema": {
            "$ref": "#/components/schemas/UserJid"
          }
        }
      ],
      "get": {
        "summary": "Perfil comercial de um contato",
        "operationId": "get-number-business-profile-jid",
        "description": "Conta pessoal responde 200 com `data: null`.\n\nEscopo: `engine:read`.",
        "tags": [
          "Perfil comercial"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Operação concluída pelo WhatsApp; `data` traz o resultado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/BusinessProfile"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/OperationPending"
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/OperationFailed",
            "description": "A operação falhou no WhatsApp; `error.code` traz o motivo informado pelo motor (ex.: `invalid_jid`, `not_allowed`)."
          },
          "502": {
            "$ref": "#/components/responses/OutcomeUnknown"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          },
          "504": {
            "$ref": "#/components/responses/EngineTimeout"
          }
        }
      }
    },
    "/v1/events/stream": {
      "get": {
        "summary": "Receber eventos ao vivo (SSE)",
        "operationId": "get-v1-events-stream",
        "description": "Fluxo contínuo (Server-Sent Events) dos eventos da organização, da área de trabalho ou de um número, conforme a chave.\n\nCada evento chega assim:\n\n```\nid: <instance_id>:<sequence>\nevent: message.received\ndata: {\"event_id\":\"…\",\"type\":\"message.received\",\"resource_id\":\"…\",\"sequence\":42,…}\n```\n\nO servidor manda `retry: 3000` no início, um comentário `: heartbeat` a cada 15 segundos e encerra a conexão depois de 10 minutos. Reconecte enviando o último `id` recebido no cabeçalho `Last-Event-ID` (o `EventSource` do navegador faz isso sozinho) para continuar de onde parou. Sem `Last-Event-ID`, `last_event_id` nem `after_sequence`, começa a partir de agora.\n\n## Navegador (`EventSource`)\nO `EventSource` não envia `Authorization`. Peça um token com `POST /v1/events/stream-token` (no seu servidor, com a chave) e abra `GET /v1/events/stream?token=…`. O token vale 5 minutos e pode ser reaproveitado nas reconexões automáticas; a chave é conferida de novo a cada abertura e a cada `heartbeat` (chave revogada encerra o fluxo). Vencido: 401 `stream_token_expired` — peça outro.\n\n## Retomada exata com vários números (`cursor=map`)\nNo formato padrão, o `id` é do número daquele evento: num fluxo de **vários** números, retomar por ele é aproximado (os outros números voltam a partir do horário desse evento). Com `cursor=map`, o `id` vira `m1.<base64url>`, um mapa da última sequência de **cada** número (até 100 números com eventos; acima disso, 400 `cursor_map_too_large`). O servidor também manda um `id` sem evento logo no início e a cada `heartbeat`, para que a reconexão seja exata mesmo antes do primeiro evento. O formato padrão não muda para quem não pede `cursor=map`.\n\n## Ordem, repetição e perda\nNão há ordem global entre números: a ordem vale **por número**, pela `sequence` (crescente, sem lacunas). Trate cada `event_id` uma vez só (o mesmo evento pode chegar de novo após uma reconexão). Para buscar o que perdeu num número, use `GET …/events?after_sequence=`.\n\nEscopo: `engine:read` (todos os eventos), `calls:read` (só `call.*`, inclusive `call.recording_*`) ou `crm:read` (só `ticket.*`, `lead.stage_changed` e `csat.answered`). Com escopo restrito, `types` só pode pedir tipos permitidos (senão 403 `scope_denied`); sem `types`, o fluxo traz só os permitidos.",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "engine:read",
          "calls:read",
          "crm:read"
        ],
        "parameters": [
          {
            "name": "Last-Event-ID",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 4096,
              "pattern": "^([0-9a-fA-F-]{36}:\\d{1,15}|m1\\.[A-Za-z0-9_-]*)$"
            },
            "description": "Último `id` recebido (`<instance_id>:<sequence>` ou o mapa `m1.…`). Vence `last_event_id`. Inválido é ignorado (começa a partir de agora)."
          },
          {
            "name": "last_event_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 4096
            },
            "description": "O mesmo que `Last-Event-ID`, na URL (útil no primeiro `EventSource`, que não manda cabeçalho). Inválido: 400 `invalid_last_event_id`."
          },
          {
            "name": "token",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 2048
            },
            "description": "Token de `POST /v1/events/stream-token`, no lugar do cabeçalho `Authorization`."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "map"
              ]
            },
            "description": "`map`: o `id` de cada evento traz a posição exata de todos os números (veja acima)."
          },
          {
            "name": "instance_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Só os eventos deste número."
          },
          {
            "name": "types",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 2000
            },
            "description": "Tipos separados por vírgula, do catálogo `EventType` (ex.: `message.received,message.read`)."
          },
          {
            "name": "after_sequence",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Começa depois desta sequência (exige um número: `instance_id` ou chave presa a ele)."
          }
        ],
        "responses": {
          "200": {
            "description": "Fluxo `text/event-stream`. Cada `data:` é um `OutboxEvent` em JSON.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                },
                "example": "retry: 3000\nid: m1.AAECAwQFBgcICQoLDA0ODwAAAAAAAAAq\n\nid: m1.AAECAwQFBgcICQoLDA0ODwAAAAAAAAAr\nevent: call.ringing\ndata: {\"event_id\":\"7d0c3e9a-5b1f-4c2e-9a77-0f6d2b8e4c11\",\"type\":\"call.ringing\",\"workspace_id\":\"2b6f1c9e-8a4d-4e7b-9c3a-5d1e0f2a6b7c\",\"instance_id\":\"00010203-0405-0607-0809-0a0b0c0d0e0f\",\"resource_id\":\"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d\",\"sequence\":43,\"occurred_at\":\"2026-10-30T14:02:11.000Z\"}\n\n: heartbeat\nid: m1.AAECAwQFBgcICQoLDA0ODwAAAAAAAAAr\n",
                "x-event-data": {
                  "$ref": "#/components/schemas/OutboxEvent"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `after_sequence_requires_instance`, `invalid_last_event_id`, `cursor_map_too_large`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized",
            "description": "`unauthorized` (chave ou token inválido, chave revogada), `stream_token_expired`"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied",
            "description": "`scope_denied` (sem escopo de eventos, ou `types` fora do escopo), `organization_suspended`, `plan_feature_required` (com `token`)"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited",
            "description": "`rate_limited` (só com `token`: a abertura conta nos pedidos por minuto da conta)"
          }
        }
      }
    },
    "/v1/events/stream-token": {
      "post": {
        "summary": "Token para o fluxo SSE no navegador",
        "operationId": "post-v1-events-stream-token",
        "description": "Gera, para a chave que chama, um token de 5 minutos para abrir `GET /v1/events/stream?token=…` sem o cabeçalho `Authorization` (o `EventSource` do navegador não envia cabeçalhos). Chame do seu servidor e entregue só o token ao navegador: ele não serve para nenhuma outra rota.\n\nO token leva só os escopos de eventos da chave e as mesmas restrições de área de trabalho e número; a chave é conferida de novo em cada abertura e a cada `heartbeat`. Só é emitido para chave de API (`fzk_`): com token OAuth (`fzo_`), 403 `stream_token_requires_api_key` (use `Authorization` no fluxo). Pode ser reaproveitado durante os 5 minutos (reconexões); depois, 401 `stream_token_expired`.\n\nEscopo: `engine:read`, `calls:read` ou `crm:read` (o mesmo do fluxo).",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "engine:read",
          "calls:read",
          "crm:read"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "201": {
            "description": "Token criado.",
            "headers": {
              "Cache-Control": {
                "description": "`no-store`.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StreamToken"
                    }
                  },
                  "additionalProperties": false
                },
                "example": {
                  "data": {
                    "token": "fzs1.eyJ2IjoxLCJrIjoiLi4uIn0.q1w2e3r4t5y6u7i8o9p0a1s2d3f4g5h6j7k8l9z0x1c",
                    "expires_at": "2026-10-30T14:05:00.000Z",
                    "url": "/v1/events/stream?token=fzs1.eyJ2IjoxLCJrIjoiLi4uIn0.q1w2e3r4t5y6u7i8o9p0a1s2d3f4g5h6j7k8l9z0x1c"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input` (o corpo, se houver, deve ser `{}`)"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          }
        }
      }
    },
    "/v1/events/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "`event_id` do aviso, ou o ID do evento do motor (`resource_id`).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Ler um evento",
        "operationId": "get-v1-events-id",
        "description": "Conteúdo de um evento que não é mensagem.\n\n- **Eventos do motor** (conexão, grupos, chamadas, etiquetas…): aceita o `resource_id` ou o `event_id` do aviso e devolve o evento decifrado (`EngineEvent`).\n- **Funil, atendimento e gravações** (`ticket.*`, `lead.stage_changed`, `csat.answered`, `call.recording_ready`, `call.recording_deleted`, `call.recording_failed`): pelo `event_id` do aviso, devolve `ControlEvent`, com o recurso **como está agora** (o atendimento, o estado do lead ou a ligação; `null` se foi apagado). Quem mudou e o motivo estão no histórico do atendimento (`GET …/tickets/{id}/events`).\n- **Mensagens**: 404 `use_message_routes` (leia em `GET /v1/messages/{id}` ou `GET …/inbound/{id}`).\n\nEscopo: `engine:read` lê todos; `calls:read` só `call.*`; `crm:read` só funil e atendimento. Evento fora do escopo: 403 `scope_denied`.",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "engine:read",
          "calls:read",
          "crm:read"
        ],
        "responses": {
          "200": {
            "description": "O evento.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/EngineEvent"
                        },
                        {
                          "$ref": "#/components/schemas/ControlEvent"
                        }
                      ]
                    }
                  }
                },
                "examples": {
                  "motor": {
                    "summary": "Evento do motor",
                    "value": {
                      "data": {
                        "id": "5f3c2b1a-9e8d-4c7b-a6f5-0e1d2c3b4a59",
                        "kind": "call.offer",
                        "workspace_id": "2b6f1c9e-8a4d-4e7b-9c3a-5d1e0f2a6b7c",
                        "instance_id": "8c7b6a59-4d3e-4f2a-9b1c-0d9e8f7a6b5c",
                        "observed_at": "2026-10-30T14:00:00.000Z",
                        "created_at": "2026-10-30T14:00:00.120Z",
                        "payload": {
                          "call_id": "8F2C0A1B9D",
                          "from": "5511912345678@s.whatsapp.net"
                        }
                      }
                    }
                  },
                  "atendimento": {
                    "summary": "Atendimento resolvido",
                    "value": {
                      "data": {
                        "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
                        "kind": "ticket.resolved",
                        "workspace_id": "2b6f1c9e-8a4d-4e7b-9c3a-5d1e0f2a6b7c",
                        "instance_id": "8c7b6a59-4d3e-4f2a-9b1c-0d9e8f7a6b5c",
                        "observed_at": "2026-10-30T14:10:00.000Z",
                        "created_at": "2026-10-30T14:10:00.000Z",
                        "sequence": 1287,
                        "payload": {
                          "resource_type": "ticket",
                          "resource_id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",
                          "ticket": {
                            "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",
                            "contact": "+5511912345678",
                            "lead": null,
                            "status": "resolved",
                            "assigned_user_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
                            "opened_at": "2026-10-30T13:40:00.000Z",
                            "resolved_at": "2026-10-30T14:10:00.000Z",
                            "resolved_by_user_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
                            "reopen_count": 0,
                            "csat": {
                              "status": "pending",
                              "score": null,
                              "sent_at": null,
                              "answered_at": null
                            },
                            "pending": null,
                            "updated_at": "2026-10-30T14:10:00.000Z"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound",
            "description": "`not_found`, `use_message_routes`"
          }
        }
      }
    },
    "/v1/webhook-endpoints": {
      "post": {
        "summary": "Cadastrar endereço de webhook",
        "operationId": "post-v1-webhook-endpoints",
        "description": "Chave válida para a área de trabalho inteira (não presa a um número). O `secret` aparece só nesta resposta.\n\nFiltros opcionais: `event_types` (só esses tipos) e `instance_ids` (só esses números da área). Sem filtro, o endereço recebe todos os tipos de todos os números da área, inclusive os criados depois.\n\nEscopo: `webhooks:write`.",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "webhooks:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEndpointInput"
              },
              "examples": {
                "todos": {
                  "summary": "Todos os eventos da área",
                  "value": {
                    "workspace_id": "2f1c7a52-3f6e-4f1b-9a51-0d8f3c2b9e10",
                    "url": "https://hooks.exemplo.com.br/flowzap"
                  }
                },
                "filtrado": {
                  "summary": "Só mensagens recebidas e atendimentos de um número",
                  "value": {
                    "workspace_id": "2f1c7a52-3f6e-4f1b-9a51-0d8f3c2b9e10",
                    "url": "https://hooks.exemplo.com.br/atendimento",
                    "event_types": [
                      "message.received",
                      "ticket.opened",
                      "ticket.resolved"
                    ],
                    "instance_ids": [
                      "7b0e2d11-8c4a-4d2e-b7f3-5a9c1e6d4f20"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Cadastrado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookEndpointCreated"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "5d3a9e70-1b2c-4f8d-a6e5-3c7b9f1d2e40",
                    "workspace_id": "2f1c7a52-3f6e-4f1b-9a51-0d8f3c2b9e10",
                    "url": "https://hooks.exemplo.com.br/atendimento",
                    "state": "active",
                    "secret_kid": "c4e8a1f2-6b3d-4e9a-8f7c-2d1b5a9e3c60",
                    "event_types": [
                      "message.received",
                      "ticket.opened",
                      "ticket.resolved"
                    ],
                    "instance_ids": [
                      "7b0e2d11-8c4a-4d2e-b7f3-5a9c1e6d4f20"
                    ],
                    "created_at": "2026-10-30T12:00:00.000Z",
                    "updated_at": "2026-10-30T12:00:00.000Z",
                    "secret": "q8Zt3X0bN1kR5mV7cY2wP9sA4dF6gH8jL0zQ2xC4vB6"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input` (inclui tipo de evento fora do catálogo), `unsafe_webhook_destination`, `instance_not_in_workspace`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`endpoint_exists`, `endpoint_limit_reached`"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`webhook_dns_unavailable`"
          }
        }
      },
      "get": {
        "summary": "Listar endereços de webhook",
        "operationId": "get-v1-webhook-endpoints",
        "description": "Até 200 endereços da área de trabalho, em qualquer estado (removidos aparecem como `disabled`). Escopo: `webhooks:read`.",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "webhooks:read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "2f1c7a52-3f6e-4f1b-9a51-0d8f3c2b9e10"
          }
        ],
        "responses": {
          "200": {
            "description": "Endereços da área de trabalho.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookEndpoint"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "5d3a9e70-1b2c-4f8d-a6e5-3c7b9f1d2e40",
                      "workspace_id": "2f1c7a52-3f6e-4f1b-9a51-0d8f3c2b9e10",
                      "url": "https://hooks.exemplo.com.br/atendimento",
                      "state": "active",
                      "secret_kid": "c4e8a1f2-6b3d-4e9a-8f7c-2d1b5a9e3c60",
                      "event_types": null,
                      "instance_ids": null,
                      "created_at": "2026-10-30T12:00:00.000Z",
                      "updated_at": "2026-10-30T12:00:00.000Z"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`workspace_id_required`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/webhook-endpoints/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do endereço de webhook.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Ver um endereço de webhook",
        "operationId": "get-v1-webhook-endpoints-id",
        "description": "O endereço em qualquer estado, com os filtros e quantos avisos estão guardados (`held_deliveries`) enquanto pausado. Chave presa a um número: 403; presa a outra área de trabalho ou de outra organização: 404.\n\nEscopo: `webhooks:read`.",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "webhooks:read"
        ],
        "responses": {
          "200": {
            "description": "O endereço.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookEndpointDetail"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "5d3a9e70-1b2c-4f8d-a6e5-3c7b9f1d2e40",
                    "workspace_id": "2f1c7a52-3f6e-4f1b-9a51-0d8f3c2b9e10",
                    "url": "https://hooks.exemplo.com.br/atendimento",
                    "state": "paused",
                    "secret_kid": "c4e8a1f2-6b3d-4e9a-8f7c-2d1b5a9e3c60",
                    "event_types": [
                      "message.received"
                    ],
                    "instance_ids": null,
                    "created_at": "2026-10-30T12:00:00.000Z",
                    "updated_at": "2026-10-30T13:10:00.000Z",
                    "held_deliveries": 42
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "summary": "Alterar endereço de webhook",
        "operationId": "patch-v1-webhook-endpoints-id",
        "description": "Muda o endereço (`url`, conferido de novo contra destinos privados), os filtros (`event_types`, `instance_ids`; `null` tira o filtro) e o estado (`active` ou `paused`). Só os campos enviados mudam; corpo vazio é 400.\n\n**Pausa sem perder avisos.** Com o endereço `paused` (por você, ou pelo FlowZap depois de 401/403 três vezes ou de um destino bloqueado), cada aviso novo fica guardado como `held` (até 10.000 por endereço; acima disso o aviso não é guardado para ele). Ao voltar para `active`, os guardados dos últimos 7 dias entram na fila na ordem em que aconteceram (`released_deliveries` diz quantos) e os mais antigos terminam como `dead` com `held_expired`. As entregas que já estavam pendentes quando pausou continuam de onde pararam.\n\nEndereço removido (`disabled`): 409 `endpoint_disabled` — cadastre outro. Chave presa a um número: 403.\n\nEscopo: `webhooks:write`.",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "webhooks:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEndpointPatch"
              },
              "examples": {
                "reativar": {
                  "summary": "Reativar um endereço pausado",
                  "value": {
                    "state": "active"
                  }
                },
                "filtros": {
                  "summary": "Trocar os filtros",
                  "value": {
                    "event_types": [
                      "message.received",
                      "message.failed"
                    ],
                    "instance_ids": null
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Alterado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookEndpointUpdated"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "5d3a9e70-1b2c-4f8d-a6e5-3c7b9f1d2e40",
                    "workspace_id": "2f1c7a52-3f6e-4f1b-9a51-0d8f3c2b9e10",
                    "url": "https://hooks.exemplo.com.br/atendimento",
                    "state": "active",
                    "secret_kid": "c4e8a1f2-6b3d-4e9a-8f7c-2d1b5a9e3c60",
                    "event_types": [
                      "message.received"
                    ],
                    "instance_ids": null,
                    "created_at": "2026-10-30T12:00:00.000Z",
                    "updated_at": "2026-10-30T14:00:00.000Z",
                    "released_deliveries": 42
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `unsafe_webhook_destination`, `instance_not_in_workspace`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`endpoint_exists` (outro endereço ativo da área já usa essa URL), `endpoint_disabled`"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`webhook_dns_unavailable`"
          }
        }
      },
      "delete": {
        "summary": "Remover endereço de webhook",
        "operationId": "delete-v1-webhook-endpoints-id",
        "description": "Para de entregar (estado `disabled`); avisos guardados (`held`) terminam como `dead` com `endpoint_disabled`. Chave presa a um número: 403. Escopo: `webhooks:write`.",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "webhooks:write"
        ],
        "responses": {
          "204": {
            "description": "Feito, sem corpo."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/webhook-endpoints/{id}/ping": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do endereço de webhook.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Testar endereço de webhook (ping)",
        "operationId": "post-v1-webhook-endpoints-id-ping",
        "description": "Envia agora um aviso de teste assinado e responde com o resultado (espera até 15 s). Mesmos cabeçalhos (`X-Flow-Timestamp`, `X-Flow-Event-Id`, `X-Flow-Signature`) e a mesma assinatura de um aviso real; o corpo traz `type: \"webhook.ping\"`, `instance_id: null`, `sequence: 0` e `data.resource_id: null` (esquema `WebhookPingBody`). Nada é guardado: não vira evento, não entra no histórico de entregas e não é repetido. Vale para endereços ativos e pausados (teste antes de reativar); removido: 409 `endpoint_disabled`.\n\nUm teste por endereço a cada 5 segundos (429 `rate_limited` com `Retry-After`). Sem corpo no pedido.\n\nEscopo: `webhooks:write`.",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "webhooks:write"
        ],
        "responses": {
          "200": {
            "description": "Teste feito; `delivered` diz se o seu endereço respondeu 2xx.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookPingResult"
                    }
                  }
                },
                "examples": {
                  "entregue": {
                    "summary": "O endereço respondeu 204",
                    "value": {
                      "data": {
                        "delivered": true,
                        "status": 204,
                        "duration_ms": 182,
                        "error_code": null
                      }
                    }
                  },
                  "falhou": {
                    "summary": "O endereço respondeu 500",
                    "value": {
                      "data": {
                        "delivered": false,
                        "status": 500,
                        "duration_ms": 95,
                        "error_code": "unexpected_status"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`endpoint_disabled`"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited",
            "description": "`rate_limited`: um teste por endereço a cada 5 s; espere o `Retry-After`."
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`webhook_secret_unavailable`"
          }
        }
      }
    },
    "/v1/webhook-endpoints/{id}/rotate-secret": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do endereço de webhook.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Trocar o segredo de um webhook",
        "operationId": "post-v1-webhook-endpoints-id-rotate-secret",
        "description": "Gera um segredo novo e o devolve **uma vez** (`secret`, base64url, com o `secret_kid` novo). O segredo anterior continua assinando por 24 horas (`previous_secret_valid_until`): nesse período cada aviso traz `X-Flow-Signature` com dois valores separados por vírgula, `v1:<secret_kid novo>:<hex>,v1:<secret_kid anterior>:<hex>`, e o seu sistema aceita o aviso quando qualquer um confere com o segredo que você guarda. Troque o segredo no seu sistema dentro das 24 horas; depois disso só o novo assina. Trocar de novo dentro das 24 horas descarta o mais antigo.\n\nExige `Idempotency-Key`: repetir com a mesma chave (e a mesma chave de API) devolve o mesmo segredo com `Idempotent-Replay: true`, sem trocar de novo; uma `Idempotency-Key` nova troca de novo. Se outra troca já aconteceu depois daquela, repetir a chave antiga responde 409 `idempotency_conflict` e não troca de novo (o que descartaria o segredo daquela troca): ele segue assinando como o anterior, ao lado do da troca mais recente, até o fim das 24 horas. Sem o segredo em mãos, faça uma troca nova com outra `Idempotency-Key`. Vale para endereços ativos ou pausados; removido, 404. Chave presa a um número: 403; presa a outra área de trabalho: 404.\n\nEscopo: `webhooks:write`.",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "webhooks:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "responses": {
          "200": {
            "description": "Segredo trocado (ou a repetição de uma troca já feita, com `Idempotent-Replay: true`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "id",
                        "workspace_id",
                        "url",
                        "state",
                        "secret_kid",
                        "secret",
                        "previous_secret_kid",
                        "previous_secret_valid_until",
                        "rotated_at"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "workspace_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "url": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "active",
                            "paused"
                          ]
                        },
                        "secret_kid": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "secret": {
                          "type": "string",
                          "description": "O segredo novo, em base64url. Guarde agora."
                        },
                        "previous_secret_kid": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "previous_secret_valid_until": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "rotated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "5d3a9e70-1b2c-4f8d-a6e5-3c7b9f1d2e40",
                    "workspace_id": "2f1c7a52-3f6e-4f1b-9a51-0d8f3c2b9e10",
                    "url": "https://hooks.exemplo.com.br/atendimento",
                    "state": "active",
                    "secret_kid": "8a2f4c6e-1d3b-8e5f-9a7c-0b2d4f6a8c10",
                    "secret": "Zb1x9W3mQ7rT5yU2iO8pA6sD4fG0hJ3kL1zX9cV7bN5",
                    "previous_secret_kid": "c4e8a1f2-6b3d-4e9a-8f7c-2d1b5a9e3c60",
                    "previous_secret_valid_until": "2026-10-31T12:00:00.000Z",
                    "rotated_at": "2026-10-30T12:00:00.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_key_required`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`: a troca desta `Idempotency-Key` já foi substituída por uma troca mais recente; nada foi trocado."
          },
          "429": {
            "$ref": "#/components/responses/AccountRateLimited"
          }
        }
      }
    },
    "/v1/webhook-deliveries": {
      "get": {
        "summary": "Histórico de entregas de webhook",
        "operationId": "get-v1-webhook-deliveries",
        "description": "Entregas da área de trabalho, das mais recentes para as mais antigas, com tentativas, rodada e último erro. Sem filtros, responde como antes: as 200 mais recentes (agora com `next_cursor` para continuar).\n\nFiltros: `endpoint_id`, `state` (inclui `held`), `event_type`, `since` (criadas a partir de, ISO 8601). Paginação: `limit` (1 a 200, padrão 200) e `cursor` com o `next_cursor` da página anterior; `next_cursor: null` marca o fim. Cursor que não veio desta rota: 400 `invalid_cursor`.\n\nEscopo: `webhooks:read`.",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "webhooks:read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "2f1c7a52-3f6e-4f1b-9a51-0d8f3c2b9e10"
          },
          {
            "name": "endpoint_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "sending",
                "delivered",
                "dead",
                "held"
              ]
            },
            "example": "dead"
          },
          {
            "name": "event_type",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/EventType"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-30T00:00:00Z"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 200
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entregas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeliveryList"
                },
                "example": {
                  "data": [
                    {
                      "id": "9e4b2c70-5a1d-4f3e-8b6c-1d2e3f4a5b60",
                      "endpoint_id": "5d3a9e70-1b2c-4f8d-a6e5-3c7b9f1d2e40",
                      "event_id": "0b7c9d1e-2f3a-4b5c-9d6e-7f8a9b0c1d20",
                      "event_type": "message.received",
                      "instance_id": "7b0e2d11-8c4a-4d2e-b7f3-5a9c1e6d4f20",
                      "state": "dead",
                      "attempts": 8,
                      "round": 1,
                      "next_attempt_at": "2026-10-31T12:00:00.000Z",
                      "last_status": 500,
                      "last_error_code": "delivery_unconfirmed",
                      "delivered_at": null,
                      "dead_at": "2026-10-31T12:00:05.000Z",
                      "created_at": "2026-10-30T12:00:00.000Z"
                    }
                  ],
                  "next_cursor": "MTc2MTgyNTYwMDAwMDAwMC45ZTRiMmM3MC01YTFkLTRmM2UtOGI2Yy0xZDJlM2Y0YTViNjA"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`workspace_id_required`, `invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/webhook-deliveries/{id}/retry": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID da entrega (de `GET /v1/webhook-deliveries`).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Reenviar uma entrega de webhook",
        "operationId": "post-v1-webhook-deliveries-id-retry",
        "description": "Põe de novo na fila uma entrega `delivered` ou `dead`, numa rodada nova (`round` + 1, `attempts` zerado, mesma programação de tentativas de uma entrega nova). O aviso é o mesmo (`X-Flow-Event-Id` igual): trate repetidos pelo `event_id`. As tentativas das rodadas anteriores continuam no histórico. Até 10 rodadas por entrega.\n\nCom o endereço pausado, a entrega fica guardada (`held`) até ele voltar a `active`. Entrega ainda na fila (`pending`, `sending` ou `held`): 409 `delivery_in_progress`. Endereço removido: 409 `endpoint_disabled`. Chave presa a um número: 403.\n\nEscopo: `webhooks:write`.",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "webhooks:write"
        ],
        "responses": {
          "202": {
            "description": "Na fila (ou guardada, com o endereço pausado).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookDelivery"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "9e4b2c70-5a1d-4f3e-8b6c-1d2e3f4a5b60",
                    "endpoint_id": "5d3a9e70-1b2c-4f8d-a6e5-3c7b9f1d2e40",
                    "event_id": "0b7c9d1e-2f3a-4b5c-9d6e-7f8a9b0c1d20",
                    "event_type": "message.received",
                    "instance_id": "7b0e2d11-8c4a-4d2e-b7f3-5a9c1e6d4f20",
                    "state": "pending",
                    "attempts": 0,
                    "round": 2,
                    "next_attempt_at": "2026-10-31T13:00:00.000Z",
                    "last_status": null,
                    "last_error_code": null,
                    "delivered_at": null,
                    "dead_at": null,
                    "created_at": "2026-10-30T12:00:00.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`delivery_in_progress`, `redelivery_limit_reached`, `endpoint_disabled`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/events": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Eventos de um número, em ordem",
        "operationId": "get-number-events",
        "description": "Para buscar o que perdeu: pagine com `after_sequence` = `next_after_sequence` da resposta anterior. A `sequence` é crescente e sem lacunas por número; trate cada `event_id` uma vez só.\n\n## Retenção\nOs eventos ficam disponíveis por **pelo menos 90 dias** (`GET …/events`, `GET /v1/events/{id}`, SSE e reenvio de webhooks). Hoje nada é apagado antes de a conta ser excluída, mas não conte com eventos mais antigos que 90 dias: uma limpeza automática poderá ser ligada com aviso prévio no changelog. Os recursos (mensagens, conversas, atendimentos, ligações) têm as próprias regras de guarda.\n\nEscopo: `engine:read` (todos), `calls:read` (só `call.*`) ou `crm:read` (só funil e atendimento). Com escopo restrito, sem `types` a lista traz só os permitidos; `types` fora do escopo: 403 `scope_denied`.",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "engine:read",
          "calls:read",
          "crm:read"
        ],
        "parameters": [
          {
            "name": "types",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 2000
            },
            "description": "Tipos separados por vírgula, do catálogo `EventType` (ex.: `message.received,message.read`)."
          },
          {
            "name": "after_sequence",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Eventos depois da sequência pedida.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OutboxEvent"
                      }
                    },
                    "next_after_sequence": {
                      "type": "integer",
                      "minimum": 0
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "event_id": "7d0c3e9a-5b1f-4c2e-9a77-0f6d2b8e4c11",
                      "type": "call.ringing",
                      "workspace_id": "2b6f1c9e-8a4d-4e7b-9c3a-5d1e0f2a6b7c",
                      "instance_id": "8c7b6a59-4d3e-4f2a-9b1c-0d9e8f7a6b5c",
                      "resource_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
                      "sequence": 43,
                      "occurred_at": "2026-10-30T14:02:11.000Z"
                    }
                  ],
                  "next_after_sequence": 43
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/inbound": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Mensagens recebidas",
        "operationId": "get-number-inbound",
        "description": "Escopo: `engine:read`. Lista as mensagens que o número recebeu desde que foi conectado. O histórico que o celular envia (conversas anteriores à conexão e respostas a `history-sync`) não entra aqui nem gera `message.received` em webhooks; ele aparece nas leituras de conversas (`/chats`).",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "parameters": [
          {
            "name": "chat",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 3,
              "maxLength": 200
            },
            "description": "Telefone ou JID da conversa."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Das mais novas para as mais antigas.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InboundMessage"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",
                      "workspace_id": "2b6f1c9e-8a4d-4e7b-9c3a-5d1e0f2a6b7c",
                      "instance_id": "8c7b6a59-4d3e-4f2a-9b1c-0d9e8f7a6b5c",
                      "received_at": "2026-10-30T14:01:00.000Z",
                      "message_id": "3EB0A1B2C3D4E5F6",
                      "chat_jid": "5511912345678@s.whatsapp.net",
                      "sender_jid": "5511912345678@s.whatsapp.net",
                      "push_name": "Maria",
                      "text": "Olá, quero reservar",
                      "from_me": false,
                      "group": false,
                      "observed_at": "2026-10-30T14:01:00.000Z"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/inbound/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Ler uma mensagem recebida",
        "operationId": "get-number-inbound-id",
        "description": "Use o `resource_id` do evento `message.received`.\n\nEscopo: `engine:read`.",
        "tags": [
          "Eventos, webhooks e SSE"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "A mensagem, decifrada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/InboundMessage"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",
                    "workspace_id": "2b6f1c9e-8a4d-4e7b-9c3a-5d1e0f2a6b7c",
                    "instance_id": "8c7b6a59-4d3e-4f2a-9b1c-0d9e8f7a6b5c",
                    "received_at": "2026-10-30T14:01:00.000Z",
                    "message_id": "3EB0A1B2C3D4E5F6",
                    "chat_jid": "5511912345678@s.whatsapp.net",
                    "sender_jid": "5511912345678@s.whatsapp.net",
                    "push_name": "Maria",
                    "text": "Olá, quero reservar",
                    "from_me": false,
                    "group": false,
                    "observed_at": "2026-10-30T14:01:00.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/crm/leads": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Listar leads",
        "operationId": "get-number-crm-leads",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "ID de etiqueta de lead."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            },
            "description": "Valor de `next_cursor` da página anterior."
          }
        ],
        "responses": {
          "200": {
            "description": "Uma página de leads.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CrmLead"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/crm/leads/{contact}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "contact",
          "in": "path",
          "required": true,
          "description": "Telefone E.164 (`+` codificado como `%2B`) ou JID. Um JID `@s.whatsapp.net` vira o telefone; `@lid` continua JID.",
          "schema": {
            "type": "string",
            "maxLength": 64
          }
        }
      ],
      "get": {
        "summary": "Ler um lead",
        "operationId": "get-number-crm-leads-contact",
        "description": "Um contato `@lid` associado a um telefone em Conversas encontra o lead guardado pelo telefone, e o telefone encontra o do `@lid`; o lead do próprio contato vem primeiro. Vale também para gravar, anotar e mover.\n\nEscopo: `engine:read`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "O lead.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmLead"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "summary": "Criar ou atualizar lead",
        "operationId": "put-number-crm-leads-contact",
        "description": "`opted_in` registra o consentimento (data e origem) exigido pelas campanhas.\n\nEscopo: `engine:write`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrmLeadInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Atualizado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmLead"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Criado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmLead"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `opted_in_in_future`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`unknown_tag`, `user_not_member`, `invalid_field_value` (o valor não serve para o tipo do campo personalizado; `error.field` diz qual)"
          }
        }
      },
      "delete": {
        "summary": "Apagar lead",
        "operationId": "delete-number-crm-leads-contact",
        "description": "Apaga o contato com as anotações, os atendimentos (abertos e resolvidos, com as notas da pesquisa de satisfação) e o que as respostas automáticas guardavam dele, inclusive pelo telefone associado ao contato `…@lid` em Conversas. Não apaga as mensagens. Com `auto_create_lead` ligado nas respostas automáticas, uma nova mensagem dessa pessoa cria o contato de novo (sem consentimento).\n\nEscopo: `engine:write`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "responses": {
          "204": {
            "description": "Feito, sem corpo."
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/crm/leads/{contact}/notes": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "contact",
          "in": "path",
          "required": true,
          "description": "Telefone E.164 (`+` codificado como `%2B`) ou JID. Um JID `@s.whatsapp.net` vira o telefone; `@lid` continua JID.",
          "schema": {
            "type": "string",
            "maxLength": 64
          }
        }
      ],
      "get": {
        "summary": "Anotações do lead",
        "operationId": "get-number-crm-leads-contact-notes",
        "description": "Mais recentes primeiro, em páginas de até `limit` (padrão 200). Continue com `cursor` = `next_cursor` da página anterior; `next_cursor` nulo é a última página.\n\nEscopo: `engine:read`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 200
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            },
            "description": "Valor de `next_cursor` da página anterior."
          }
        ],
        "responses": {
          "200": {
            "description": "Uma página de anotações, mais recentes primeiro.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CrmNote"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "summary": "Criar anotação",
        "operationId": "post-number-crm-leads-contact-notes",
        "description": "Sem `author_user_id`, a autora é a chave de API (seu prefixo). Com ele, a chave só assina pela pessoa que a criou, a não ser que essa pessoa seja dona ou administradora da conta (ou da área de trabalho): aí a integração pode assinar por qualquer pessoa da equipe.\n\nEscopo: `engine:write`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrmNoteInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Criada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmNote"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Error",
            "description": "`scope_denied`: a chave não tem o escopo desta rota. `organization_suspended`: conta suspensa ou encerrada. `author_not_allowed`: `author_user_id` não é quem criou a chave, e quem a criou não é dono nem administrador (ou a chave não tem pessoa)."
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`user_not_member`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/crm/leads/{contact}/opt-out": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "contact",
          "in": "path",
          "required": true,
          "description": "Telefone E.164 (`+` codificado como `%2B`) ou JID. Um JID `@s.whatsapp.net` vira o telefone; `@lid` continua JID.",
          "schema": {
            "type": "string",
            "maxLength": 64
          }
        }
      ],
      "post": {
        "summary": "Registrar saída da lista (opt-out)",
        "operationId": "post-number-crm-leads-contact-opt-out",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "responses": {
          "200": {
            "description": "Lead com `opted_out_at` preenchido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmLead"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/crm/notes/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "delete": {
        "summary": "Apagar anotação",
        "operationId": "delete-number-crm-notes-id",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "responses": {
          "204": {
            "description": "Feito, sem corpo."
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/crm/tags": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Listar etiquetas de lead",
        "operationId": "get-number-crm-tags",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Etiquetas (só do FlowZap; não são as do WhatsApp).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CrmTag"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "summary": "Criar etiqueta de lead",
        "operationId": "post-number-crm-tags",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrmTagInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Criada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmTag"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`tag_exists`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/crm/tags/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "delete": {
        "summary": "Apagar etiqueta de lead",
        "operationId": "delete-number-crm-tags-id",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "responses": {
          "204": {
            "description": "Feito, sem corpo."
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/crm/stages": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Listar etapas do funil",
        "operationId": "get-number-crm-stages",
        "description": "Escopo: `crm:read` (ou `engine:read`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:read"
        ],
        "responses": {
          "200": {
            "description": "Etapas em ordem. Um número sem etapas ganha as padrão: Novo, Em conversa, Proposta, Fechado (ganho) e Perdido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CrmStage"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "summary": "Criar etapa",
        "operationId": "post-number-crm-stages",
        "description": "Escopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrmStageInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Criada no fim do funil.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmStage"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`stage_exists`"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`too_many_stages` (máximo 12 por número)"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/crm/stages/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "patch": {
        "summary": "Alterar etapa",
        "operationId": "patch-number-crm-stages-id",
        "description": "Escopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrmStagePatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A etapa.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmStage"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`stage_exists`"
          }
        }
      },
      "delete": {
        "summary": "Apagar etapa",
        "operationId": "delete-number-crm-stages-id",
        "description": "Escopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "responses": {
          "204": {
            "description": "Feito, sem corpo. Os contatos da etapa ficam sem etapa."
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`last_stage`: o funil precisa de ao menos uma etapa"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/crm/pipeline": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Ver funil",
        "operationId": "get-number-crm-pipeline",
        "description": "Escopo: `crm:read` (ou `engine:read`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:read"
        ],
        "parameters": [
          {
            "name": "stage",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Só esta etapa (id) ou `none` (sem etapa). Obrigatório com `cursor`."
          },
          {
            "name": "assigned",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "`me` (a pessoa que criou a chave), `none` (sem responsável) ou o id de uma pessoa."
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Só contatos com esta etiqueta."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            },
            "description": "Valor de `next_cursor` da página anterior."
          }
        ],
        "responses": {
          "200": {
            "description": "Uma coluna por etapa (e `stage: null` para contatos sem etapa, quando há), com total e os primeiros 50 contatos.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmPipeline"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_cursor`, `cursor_needs_stage`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`no_person_for_key`: `assigned=me` com chave sem pessoa"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/crm/leads/{contact}/move": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "contact",
          "in": "path",
          "required": true,
          "description": "Telefone E.164 (`+` codificado como `%2B`) ou JID. Um JID `@s.whatsapp.net` vira o telefone; `@lid` continua JID.",
          "schema": {
            "type": "string",
            "maxLength": 64
          }
        }
      ],
      "post": {
        "summary": "Mover contato de etapa",
        "operationId": "post-number-crm-leads-contact-move",
        "description": "Mudar de etapa gera o evento `lead.stage_changed`. Repetir o mesmo movimento chega ao mesmo lugar.\n\nEscopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrmMoveInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "O contato na nova posição.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmPipelineCard"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `before_or_after` (só um dos dois)"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`unknown_stage`, `unknown_neighbor`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/crm/fields": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Listar campos personalizados",
        "operationId": "get-number-crm-fields",
        "description": "Escopo: `crm:read` (ou `engine:read`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:read"
        ],
        "responses": {
          "200": {
            "description": "Campos em ordem.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CrmField"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "summary": "Criar campo personalizado",
        "operationId": "post-number-crm-fields",
        "description": "Os valores ficam em `fields` de cada lead (`PUT …/crm/leads/{contact}`), conferidos pelo tipo ao gravar.\n\nEscopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrmFieldInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Criado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmField"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`field_exists`"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`too_many_fields` (máximo 20), `options_required`, `options_only_for_select`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/crm/fields/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "patch": {
        "summary": "Alterar campo personalizado",
        "operationId": "patch-number-crm-fields-id",
        "description": "Escopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrmFieldPatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "O campo.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CrmField"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`options_required`, `options_only_for_select`"
          }
        }
      },
      "delete": {
        "summary": "Apagar campo personalizado",
        "operationId": "delete-number-crm-fields-id",
        "description": "Escopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "responses": {
          "204": {
            "description": "Feito, sem corpo. Os valores já gravados nos contatos continuam."
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/tickets": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Listar atendimentos",
        "operationId": "get-number-tickets",
        "description": "Escopo: `crm:read` (ou `engine:read`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:read"
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "resolved"
              ]
            }
          },
          {
            "name": "assigned",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "`me` (a pessoa que criou a chave), `none` (sem responsável) ou o id de uma pessoa."
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Só atendimentos alterados a partir deste instante (`updated_at`), em ISO 8601 com fuso (por exemplo `2026-10-30T12:00:00Z`): para sincronizar só o que mudou."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            },
            "description": "Valor de `next_cursor` da página anterior."
          }
        ],
        "responses": {
          "200": {
            "description": "Uma página de atendimentos, do mais novo ao mais antigo.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Ticket"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`no_person_for_key`: `assigned=me` com chave sem pessoa"
          }
        }
      },
      "post": {
        "summary": "Abrir atendimento",
        "operationId": "post-number-tickets",
        "description": "Abre à mão o atendimento de uma conversa sem atendimento aberto, inclusive de um grupo (`group:<jid>`): mensagens recebidas abrem o de uma pessoa sozinhas, mas o de um grupo só abre assim. Se o contato já tem um aberto, ele volta como está (repetir o pedido é seguro). Gera `ticket.opened` só quando abre; o responsável vem do contato no funil, como numa mensagem recebida. Depois, use as rotas de pendência e resolver com o id devolvido. Quando abre, entra no histórico com `reason` e `actor_label`, se enviados.\n\nEscopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TicketOpenInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "O atendimento aberto (o que já estava aberto, ou um novo).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Ticket"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/tickets/csat-summary": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Resumo da pesquisa de satisfação",
        "operationId": "get-number-tickets-csat-summary",
        "description": "Escopo: `crm:read` (ou `engine:read`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:read"
        ],
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365,
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Respostas, média, notas e taxa de resposta das pesquisas enviadas no período.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CsatSummary"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/tickets/bulk": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Alterar vários atendimentos",
        "operationId": "post-number-tickets-bulk",
        "description": "Aplica uma ação (`resolve`, `reopen`, `pending_set`, `pending_clear` ou `assign`) a até 100 atendimentos, um de cada vez, com as mesmas regras e eventos das rotas de um atendimento só. Cada item é o id do atendimento, o contato (telefone E.164, `…@lid`, `group:<jid>`) ou, para um grupo sem atendimento, `{contact, name}`. `resolve` e `pending_set` abrem o atendimento de um contato que nunca teve um. A resposta traz o resultado de cada item, na ordem enviada: `applied` (a mudança vale, inclusive se já valia; repetir o pedido é seguro), `skipped` (não se aplica: `ticket_pending`, `ticket_not_open`, `ticket_already_open`, `not_found`) ou `error`. `reason` e `actor_label` entram no histórico de cada item alterado (inclusive na abertura de um atendimento que não existia).\n\nEscopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TicketBulkInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "O resultado de cada item.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TicketBulkResult"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input` (mais de 100 itens, `level` ausente em `pending_set`, `user_id` ausente em `assign`)"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`user_not_member`: a pessoa de `assign` não tem acesso ao número"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/tickets/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "O id do atendimento, ou o contato (telefone E.164 com `%2B`, `…@lid` ou o grupo `group:<jid>`): o aberto, ou o último.",
          "schema": {
            "type": "string",
            "maxLength": 64
          }
        }
      ],
      "get": {
        "summary": "Ler atendimento",
        "operationId": "get-number-tickets-id",
        "description": "Escopo: `crm:read` (ou `engine:read`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:read"
        ],
        "responses": {
          "200": {
            "description": "O atendimento.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Ticket"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/tickets/{id}/events": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "O id do atendimento, ou o contato (telefone E.164 com `%2B`, `…@lid` ou o grupo `group:<jid>`): o aberto, ou o último.",
          "schema": {
            "type": "string",
            "maxLength": 64
          }
        }
      ],
      "get": {
        "summary": "Histórico do atendimento",
        "operationId": "get-number-tickets-id-events",
        "description": "Cada mudança real do atendimento, da mais antiga à mais nova: aberto (por mensagem recebida, `via: system`, ou à mão), resolvido, reaberto, responsável trocado, pendência marcada ou retirada. Traz quem fez (`via`: `console`, `api` ou `system`; a pessoa, a chave de API e o atendente declarado em `actor_label`), o motivo, o estado antes e depois (só os campos que mudaram, nunca o contato) e o `event_id` do evento de webhook anunciado com a mudança. Repetir uma ação que já vale não gera entrada. Reabrir não apaga nada: quem resolveu e por quê continua aqui.\n\nEscopo: `crm:read` (ou `engine:read`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:read"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            },
            "description": "Valor de `next_cursor` da página anterior."
          }
        ],
        "responses": {
          "200": {
            "description": "Uma página do histórico, da mudança mais antiga à mais nova.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TicketEvent"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/tickets/{contact}/resolve": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "contact",
          "in": "path",
          "required": true,
          "description": "O id do atendimento, o telefone E.164 (`+` como `%2B`), o contato `…@lid` ou o grupo `group:<jid>`. Pelo contato vale o atendimento aberto (ou o último).",
          "schema": {
            "type": "string",
            "maxLength": 64
          }
        }
      ],
      "post": {
        "summary": "Resolver atendimento",
        "operationId": "post-number-tickets-contact-resolve",
        "description": "Gera `ticket.resolved`. Com a pesquisa de satisfação ligada no número, a pergunta entra na fila (`csat.status: pending`); um grupo nunca recebe a pesquisa. Um atendimento reaberto e resolvido de novo recebe a pesquisa outra vez, salvo se ela já foi respondida: a nota fica e nenhuma pesquisa nova é enviada. Um atendimento com pendência só é resolvido depois de retirar a pendência. Toda mudança aceita `reason` (motivo) e `actor_label` (o nome do atendente no seu sistema, guardado como enviado) e entra no histórico (`GET …/tickets/{id}/events`) com a pessoa que criou a chave e a chave.\n\nEscopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TicketResolveInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "O atendimento resolvido (um já resolvido volta como está).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Ticket"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`ticket_pending`: o atendimento tem pendência; retire-a antes de resolver"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/tickets/{contact}/reopen": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "contact",
          "in": "path",
          "required": true,
          "description": "O id do atendimento, o telefone E.164 (`+` como `%2B`), o contato `…@lid` ou o grupo `group:<jid>`. Pelo contato vale o atendimento aberto (ou o último).",
          "schema": {
            "type": "string",
            "maxLength": 64
          }
        }
      ],
      "post": {
        "summary": "Reabrir atendimento",
        "operationId": "post-number-tickets-contact-reopen",
        "description": "Gera `ticket.reopened`. `resolved_by_user_id` volta a `null`; o histórico guarda quem resolveu e por quê. O corpo é opcional: `reason` e `actor_label` entram no histórico.\n\nEscopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TicketTrailInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "O atendimento aberto (um já aberto volta como está).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Ticket"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`ticket_already_open`: o contato já tem outro atendimento aberto"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/tickets/{contact}/assignee": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "contact",
          "in": "path",
          "required": true,
          "description": "O id do atendimento, o telefone E.164 (`+` como `%2B`), o contato `…@lid` ou o grupo `group:<jid>`. Pelo contato vale o atendimento aberto (ou o último).",
          "schema": {
            "type": "string",
            "maxLength": 64
          }
        }
      ],
      "put": {
        "summary": "Atribuir atendimento",
        "operationId": "put-number-tickets-contact-assignee",
        "description": "Gera `ticket.assigned` quando o responsável muda. Toda mudança aceita `reason` (motivo) e `actor_label` (o nome do atendente no seu sistema, guardado como enviado) e entra no histórico (`GET …/tickets/{id}/events`) com a pessoa que criou a chave e a chave.\n\nEscopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TicketAssigneeInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "O atendimento.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Ticket"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`user_not_member`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/tickets/{contact}/pending": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "contact",
          "in": "path",
          "required": true,
          "description": "O id do atendimento, o telefone E.164 (`+` como `%2B`), o contato `…@lid` ou o grupo `group:<jid>`. Pelo contato vale o atendimento aberto (ou o último).",
          "schema": {
            "type": "string",
            "maxLength": 64
          }
        }
      ],
      "put": {
        "summary": "Marcar pendência no atendimento",
        "operationId": "put-number-tickets-contact-pending",
        "description": "Marca o atendimento aberto como pendente, com nível (`urgent`, `medium` ou `low`) e observação opcional. No console a conversa fica no topo da lista; o atendimento só é resolvido depois de retirar a pendência. Gera `ticket.pending_set` quando o nível ou a observação mudam (repetir o mesmo pedido devolve o atendimento como está). Toda mudança aceita `reason` (motivo) e `actor_label` (o nome do atendente no seu sistema, guardado como enviado) e entra no histórico (`GET …/tickets/{id}/events`) com a pessoa que criou a chave e a chave.\n\nEscopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TicketPendingInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "O atendimento com a pendência.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Ticket"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`ticket_not_open`: só um atendimento aberto pode ficar pendente"
          }
        }
      },
      "delete": {
        "summary": "Retirar pendência do atendimento",
        "operationId": "delete-number-tickets-contact-pending",
        "description": "Gera `ticket.pending_cleared` (sem pendência, devolve o atendimento como está). `reason` e `actor_label` vão na query string e entram no histórico.\n\nEscopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Funil e atendimentos"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "parameters": [
          {
            "name": "reason",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 280
            },
            "description": "Motivo da mudança, guardado no histórico do atendimento."
          },
          {
            "name": "actor_label",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80
            },
            "description": "Nome do atendente no seu sistema, guardado no histórico como enviado (declarado, não verificado)."
          }
        ],
        "responses": {
          "200": {
            "description": "O atendimento sem pendência.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Ticket"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/auto-replies": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Ver respostas automáticas",
        "operationId": "get-number-auto-replies",
        "description": "Configuração das respostas automáticas do número. Um número que nunca foi configurado devolve os padrões, com `updated_at: null`.\n\nEscopo: `crm:read` (ou `engine:read`).",
        "tags": [
          "Respostas automáticas"
        ],
        "x-scopes": [
          "crm:read"
        ],
        "responses": {
          "200": {
            "description": "A configuração do número.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AutoReplies"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "summary": "Alterar respostas automáticas",
        "operationId": "put-number-auto-replies",
        "description": "Substitui toda a configuração (não é merge). Respostas automáticas só respondem uma mensagem recebida de uma pessoa (nunca iniciam conversa nem respondem grupos), no máximo 5 por contato por hora, só com o número conectado, até 15 minutos depois de a mensagem chegar (passado isso, não respondem mais), e param para o contato quando alguém da equipe responde. O remetente aparece nas conversas como \"Resposta automática\" (ou \"Pesquisa de satisfação\").\n\nOs textos (boas-vindas, fora do horário, menu, palavras-chave e pesquisa) são guardados como configuração da conta, como nomes de etapas e etiquetas: não são cifrados como as mensagens. Não coloque senhas, chaves ou dados pessoais neles.\n\nEscopo: `crm:write` (ou `engine:write`).",
        "tags": [
          "Respostas automáticas"
        ],
        "x-scopes": [
          "crm:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AutoRepliesInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A configuração gravada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AutoReplies"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "`invalid_auto_replies`: `error.field` diz o caminho do primeiro problema, ex.: `menu.options.2.reply`, `away.hours.tz`, `menu.options.0.stage_id` (etapa, etiqueta ou pessoa que não existe no número).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "request_id",
                        "retryable",
                        "field"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_auto_replies"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        },
                        "field": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/quick-replies": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Listar respostas rápidas",
        "operationId": "get-number-quick-replies",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Respostas rápidas.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/QuickReply"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "summary": "Criar resposta rápida",
        "operationId": "post-number-quick-replies",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuickReplyInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Criada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/QuickReply"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`shortcut_exists`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/quick-replies/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "put": {
        "summary": "Editar resposta rápida",
        "operationId": "put-number-quick-replies-id",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuickReplyInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Salva.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/QuickReply"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`shortcut_exists`"
          }
        }
      },
      "delete": {
        "summary": "Apagar resposta rápida",
        "operationId": "delete-number-quick-replies-id",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "CRM e respostas rápidas"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "responses": {
          "204": {
            "description": "Feito, sem corpo."
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/audiences": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Coletar um público",
        "operationId": "post-number-audiences",
        "description": "Junta os participantes dos grupos em que o número **já está** num público para anúncios (Meta e Google). Lê os grupos uma única vez (sem entrar em grupo nenhum) e no máximo uma vez a cada 10 minutos por número. Cada telefone entra uma vez; o próprio número fica de fora; quem aparece sem telefone é só contado em `participants_without_phone`. **Ninguém do público recebe mensagem pelo FlowZap**: campanhas continuam exigindo consentimento. Os membros ficam cifrados e são apagados depois de 180 dias sem atualizar.\n\nResponde 201 com a coleta pronta ou 202 enquanto ainda lê os grupos (consulte `GET …/audiences/{id}`).\n\nEscopo: `audiences:write`.",
        "tags": [
          "Públicos"
        ],
        "x-scopes": [
          "audiences:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAudienceInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Repetição de um pedido já atendido (`Idempotent-Replay: true`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Audience"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Coletado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Audience"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Ainda lendo os grupos (`state: collecting`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Audience"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`collection_failed` (com `audience_id` e `reason` no erro)"
          },
          "429": {
            "$ref": "#/components/responses/Error",
            "description": "`collection_too_soon`: o número coletou há menos de 10 minutos (`retry_after_seconds` e `next_collection_at` no erro)."
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected` (nada fica criado)"
          }
        }
      },
      "get": {
        "summary": "Listar públicos",
        "operationId": "get-number-audiences",
        "description": "Escopo: `audiences:read`.",
        "tags": [
          "Públicos"
        ],
        "x-scopes": [
          "audiences:read"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "Valor de `next_cursor` da página anterior."
          }
        ],
        "responses": {
          "200": {
            "description": "Uma página de públicos.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Audience"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/audiences/members/{phone}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "phone",
          "in": "path",
          "required": true,
          "description": "Telefone E.164 com `+` (codificado na URL: `%2B5511…`).",
          "schema": {
            "type": "string",
            "pattern": "^\\+[1-9]\\d{6,14}$"
          }
        }
      ],
      "delete": {
        "summary": "Tirar uma pessoa de todos os públicos",
        "operationId": "delete-number-audiences-members-phone",
        "description": "Pedido do titular (LGPD): apaga a pessoa de todos os públicos do número e a deixa de fora das próximas coletas (fica guardado só um resumo do telefone, um hash com chave secreta). Escopo: `audiences:write`.",
        "tags": [
          "Públicos"
        ],
        "x-scopes": [
          "audiences:write"
        ],
        "responses": {
          "200": {
            "description": "Feito.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "removed_from"
                      ],
                      "properties": {
                        "removed_from": {
                          "type": "integer",
                          "description": "Em quantos públicos a pessoa estava."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/audiences/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do público.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Ler um público",
        "operationId": "get-number-audiences-id",
        "description": "Contagens, grupos de origem, quando o número pode coletar de novo e o texto da declaração exigida na exportação. Escopo: `audiences:read`.",
        "tags": [
          "Públicos"
        ],
        "x-scopes": [
          "audiences:read"
        ],
        "responses": {
          "200": {
            "description": "O público.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AudienceDetail"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "summary": "Apagar um público",
        "operationId": "delete-number-audiences-id",
        "description": "Apaga os membros e os grupos de origem na hora (LGPD). O histórico de exportações continua. Escopo: `audiences:write`.",
        "tags": [
          "Públicos"
        ],
        "x-scopes": [
          "audiences:write"
        ],
        "responses": {
          "204": {
            "description": "Apagado."
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/audiences/{id}/exports": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do público.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Exportar para Meta, Google ou planilha",
        "operationId": "post-number-audiences-id-exports",
        "description": "Devolve o arquivo CSV (`text/csv`). `meta` e `google`: para subir no Gerenciador de Anúncios do Meta (Público Personalizado) ou no Google Ads (Customer Match), com telefones e nomes em SHA-256, nunca em texto; os dois recebem o público inteiro (o Google aceita só listas de clientes da própria empresa: lista vinda de grupos de terceiros pode ser recusada por ele). `csv`: planilha com telefone completo, nome e grupos legíveis de todo o público, para eventos e listas (arquivo `publico-<nome>-<aaaa-mm-dd>.csv`); trate como dado pessoal. Toda exportação exige `declaration_accepted: true` (a planilha tem declaração própria, em `export_declarations.csv`) e fica registrada (quem, quando, quantas linhas, endereço IP e versão da declaração). A planilha não sai pelo MCP.\n\nEscopo: `audiences:export`.",
        "tags": [
          "Públicos"
        ],
        "x-scopes": [
          "audiences:export"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExportInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "O arquivo. Cabeçalhos `Content-Disposition` (nome do arquivo), `X-Export-Id` e `X-Export-Rows`.",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`audience_not_ready`: ainda sem coleta pronta, ou vencido (180 dias)."
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`declaration_required`, `audience_empty`"
          }
        }
      },
      "get": {
        "summary": "Histórico de exportações",
        "operationId": "get-number-audiences-id-exports",
        "description": "As últimas 100 exportações do público. Escopo: `audiences:read`.",
        "tags": [
          "Públicos"
        ],
        "x-scopes": [
          "audiences:read"
        ],
        "responses": {
          "200": {
            "description": "As exportações, da mais nova para a mais antiga.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AudienceExport"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/audiences/{id}/members": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do público.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Membros de um público",
        "operationId": "get-number-audiences-id-members",
        "description": "Telefones mascarados e sem nome. `full=1` mostra telefone e nome completos e exige também `audiences:export`. Escopo: `audiences:read`.",
        "tags": [
          "Públicos"
        ],
        "x-scopes": [
          "audiences:read"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            },
            "description": "Valor de `next_cursor` da página anterior."
          },
          {
            "name": "full",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Uma página de membros.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AudienceMember"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/audiences/{id}/refresh": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do público.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Atualizar um público",
        "operationId": "post-number-audiences-id-refresh",
        "description": "Coleta de novo os mesmos grupos: quem saiu do grupo sai do público. Mesmo limite de uma coleta a cada 10 minutos por número. Escopo: `audiences:write`.",
        "tags": [
          "Públicos"
        ],
        "x-scopes": [
          "audiences:write"
        ],
        "responses": {
          "200": {
            "description": "Atualizado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Audience"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Ainda lendo os grupos (`state: collecting`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Audience"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`collection_in_progress`"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`collection_failed` (com `audience_id` e `reason` no erro)"
          },
          "429": {
            "$ref": "#/components/responses/Error",
            "description": "`collection_too_soon` (`retry_after_seconds` e `next_collection_at` no erro)"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `number_not_connected`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/message-templates": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        }
      ],
      "get": {
        "summary": "Listar modelos de mensagem",
        "operationId": "get-workspace-message-templates",
        "description": "Os modelos da conta (`workspace_id` nulo) e os desta área de trabalho, por nome, com as variáveis que o envio precisa preencher.\n\nEscopo: `messages:read`.",
        "tags": [
          "Modelos e agendamentos"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/TemplateCategory"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Os modelos (até 500).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ModelosMessageTemplate"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "summary": "Criar modelo de mensagem",
        "operationId": "post-workspace-message-templates",
        "description": "Um modelo para avisos, cobranças e lembretes: texto (ou arquivo por link com legenda) com dados do CRM (`{{primeiro_nome}}`…) e variáveis livres (`{{var:link}}`…) preenchidas no envio. Por padrão vale para todos os números da conta; uma chave presa a uma área de trabalho ou número cria modelos só da sua área (e não muda os da conta: 403 `template_read_only`). `Idempotency-Key` é opcional.\n\nEscopo: `messages:send`.",
        "tags": [
          "Modelos e agendamentos"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessageTemplateInput"
              },
              "examples": {
                "carrinho": {
                  "summary": "Carrinho abandonado",
                  "value": {
                    "name": "Carrinho abandonado",
                    "category": "aviso",
                    "message": {
                      "type": "text",
                      "text": {
                        "body": "Oi {{primeiro_nome|tudo bem}}! Você deixou {{var:produto}} no carrinho. Finalize aqui: {{var:link}} {{var:cupom|}}"
                      }
                    }
                  }
                },
                "pix": {
                  "summary": "Lembrete de Pix",
                  "value": {
                    "name": "Lembrete de Pix",
                    "category": "cobranca",
                    "message": {
                      "type": "text",
                      "text": {
                        "body": "Olá {{primeiro_nome|cliente}}, o pagamento de {{var:valor}} vence em {{var:data}}. Pix copia e cola: {{var:pix}}"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Repetição de um pedido já atendido (`Idempotent-Replay: true`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ModelosMessageTemplate"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Criado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ModelosMessageTemplate"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input` (inclui arquivo que não é link https), `invalid_idempotency_key`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`template_name_exists`, `idempotency_conflict`"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_placeholder` (com `placeholder`)"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/message-templates/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Ler um modelo",
        "operationId": "get-workspace-message-templates-id",
        "description": "Escopo: `messages:read`.",
        "tags": [
          "Modelos e agendamentos"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "responses": {
          "200": {
            "description": "O modelo.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ModelosMessageTemplate"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound",
            "description": "`not_found`, `template_not_found`"
          }
        }
      },
      "put": {
        "summary": "Alterar um modelo",
        "operationId": "put-workspace-message-templates-id",
        "description": "Troca nome, tipo e mensagem. Envios já agendados guardam a mensagem de quando foram criados.\n\nEscopo: `messages:send`.",
        "tags": [
          "Modelos e agendamentos"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessageTemplateUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "O modelo alterado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ModelosMessageTemplate"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied",
            "description": "`scope_denied`, `template_read_only` (modelo da conta e chave presa a uma área de trabalho)"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`template_name_exists`"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_placeholder`"
          }
        }
      },
      "delete": {
        "summary": "Apagar um modelo",
        "operationId": "delete-workspace-message-templates-id",
        "description": "Envios já agendados com ele continuam (guardam a própria mensagem).\n\nEscopo: `messages:send`.",
        "tags": [
          "Modelos e agendamentos"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "responses": {
          "204": {
            "description": "Apagado."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied",
            "description": "`scope_denied`, `template_read_only`"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/messages/template": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Enviar por modelo",
        "operationId": "post-number-messages-template",
        "description": "Preenche o modelo para a pessoa (dados do CRM do número + `variables`) e envia pelo mesmo caminho de `POST …/messages`: envio liberado no plano, conta dentro do limite de números (409 `numbers_over_limit`), limites por chave e fila (429), assinatura do número. Sem `scheduled_at`: **202** com o envio (como `POST …/messages`; expira em 2 h se não sair). Com `scheduled_at`: **201** com a mensagem agendada (`GET …/scheduled-messages/{id}`).\n\n`Idempotency-Key` (ou `idempotency_key` no corpo) é obrigatória: repetir devolve o mesmo envio sem preencher de novo; com outros dados, 409 `idempotency_conflict`. Uma recusa (por exemplo 503 `send_unavailable`) não guarda nada, e a mesma chave pode tentar de novo. Faltou variável sem alternativo: 422 `missing_variables` com `missing`.\n\nEscopo: `messages:send`.",
        "tags": [
          "Modelos e agendamentos"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendTemplateInput"
              },
              "examples": {
                "carrinho": {
                  "summary": "Carrinho abandonado (na hora)",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "template_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
                    "variables": {
                      "nome": "Ana Souza",
                      "produto": "Tênis Corrida 42",
                      "link": "https://loja.exemplo/carrinho/abc123"
                    },
                    "client_reference": "carrinho-abc123"
                  }
                },
                "pix": {
                  "summary": "Lembrete de Pix (agendado)",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "template_id": "2f1c9a54-6b0d-4c8e-9a7b-3d5e8f1a2b3c",
                    "variables": {
                      "valor": "R$ 189,90",
                      "data": "20/10",
                      "pix": "00020126580014br.gov.bcb.pix…"
                    },
                    "scheduled_at": "2026-10-19T09:00:00-03:00",
                    "client_reference": "fatura-2026-10"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agendamento repetido com a mesma chave (`Idempotent-Replay: true`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ScheduledMessage"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Agendada (`scheduled_at`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ScheduledMessage"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Na fila (sem `scheduled_at`). Repetição: `Idempotent-Replay: true`.",
            "headers": {
              "Idempotent-Replay": {
                "$ref": "#/components/headers/IdempotentReplay"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MessageCommand"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `idempotency_key_required`, `invalid_idempotency_key`, `idempotency_key_mismatch`, `invalid_expiry`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound",
            "description": "`not_found`, `template_not_found`"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`, `numbers_over_limit`, `operator_name_required`, `too_many_scheduled`"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`missing_variables` (com `missing`), `invalid_placeholder`, `invalid_message`, `invalid_schedule` (com `earliest` e `latest`)"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`send_unavailable`, `engine_unavailable`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/scheduled-messages": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Agendar mensagem",
        "operationId": "post-number-scheduled-messages",
        "description": "Uma mensagem avulsa (`message`) ou um modelo (`template_id` + `variables`) para um telefone ou grupo, de 1 minuto a 90 dias à frente. A mensagem é preenchida agora (faltas respondem 422 já) e sai no horário pelo mesmo caminho de `POST …/messages`, **uma vez só**, mesmo se o serviço reiniciar. Número desconectado no horário: novas tentativas a cada minuto por 1 hora; depois, `failed` com `error_code`. Até 1.000 agendadas por número.\n\nEscopo: `messages:send`.",
        "tags": [
          "Modelos e agendamentos"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScheduleMessageInput"
              },
              "examples": {
                "consulta": {
                  "summary": "Lembrete de consulta",
                  "value": {
                    "to": {
                      "kind": "phone",
                      "value": "+5511912345678"
                    },
                    "scheduled_at": "2026-10-20T08:00:00-03:00",
                    "message": {
                      "type": "text",
                      "text": {
                        "body": "Bom dia! Lembrete: sua consulta é hoje às 14h. Responda 1 para confirmar."
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Repetição com a mesma chave (`Idempotent-Replay: true`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ScheduledMessage"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Agendada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ScheduledMessage"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `idempotency_key_required`, `invalid_idempotency_key`, `idempotency_key_mismatch`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound",
            "description": "`not_found`, `template_not_found`"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`, `too_many_scheduled`"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_schedule`, `missing_variables`, `invalid_placeholder`, `invalid_message`, `media_expires_before_schedule`"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`"
          }
        }
      },
      "get": {
        "summary": "Listar mensagens agendadas",
        "operationId": "get-number-scheduled-messages",
        "description": "Por situação (padrão `scheduled`, mais próximas primeiro; as outras, mais recentes primeiro). Envios imediatos por modelo não aparecem aqui.\n\nEscopo: `messages:read`.",
        "tags": [
          "Modelos e agendamentos"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "scheduled",
                "accepted",
                "failed",
                "canceled"
              ],
              "default": "scheduled"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            },
            "description": "Valor de `next_cursor` da página anterior."
          }
        ],
        "responses": {
          "200": {
            "description": "Uma página.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ScheduledMessage"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/scheduled-messages/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Ler uma mensagem agendada",
        "operationId": "get-number-scheduled-messages-id",
        "description": "Escopo: `messages:read`.",
        "tags": [
          "Modelos e agendamentos"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "responses": {
          "200": {
            "description": "A mensagem agendada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ScheduledMessage"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/scheduled-messages/{id}/cancel": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Cancelar mensagem agendada",
        "operationId": "post-number-scheduled-messages-id-cancel",
        "description": "Cancela uma mensagem que ainda aguarda. Cancelar de novo responde o mesmo. Se ela já saiu (mesmo que o registro ainda não mostrasse), 409 `already_sent` com `message_id`; em outra situação, 409 `not_cancelable` com `state`.\n\nEscopo: `messages:send`.",
        "tags": [
          "Modelos e agendamentos"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "responses": {
          "200": {
            "description": "Cancelada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ScheduledMessage"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`already_sent`, `not_cancelable`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/group-broadcasts": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Enviar mensagem a vários grupos",
        "operationId": "post-number-group-broadcasts",
        "description": "A mesma mensagem para vários grupos em que o número é **administrador** — grupos em que ele só participa são recusados (422 `not_group_admin`, com `not_admin` e `not_found` no erro) ou pulados com `skip_non_admin`. A conferência é uma leitura dos grupos no WhatsApp (sem participantes); enquanto ela não termina, 503 `groups_not_ready`: repita com a mesma `Idempotency-Key`. Antes de cada grupo o envio confere de novo (uma leitura por envio a cada 10 minutos no máximo): um grupo em que o número deixou de ser administrador, ou que não existe mais, fica `failed` com `error_code` `not_group_admin` ou `group_not_found`, sem mensagem.\n\nUma mensagem por grupo, nunca repetida (chave `group-broadcast:<envio>:<grupo>`). Proteções das campanhas: pausa aleatória entre grupos (padrão 10 a 30 s), `daily_limit` por número (padrão 200, dia de Brasília, somando os envios para grupos do número), `window` e pausa automática `paused_by_safety` (mais de 20% de falhas nos últimos 50 envios, ou limite do WhatsApp para o número). Até 500 grupos e 10 envios ativos por número. Exige `Idempotency-Key`.\n\nEscopo: `messages:send` (ou `campaigns:write`).",
        "tags": [
          "Lançamento em grupos"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateGroupBroadcastInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Repetição de um pedido já atendido (`Idempotent-Replay: true`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupBroadcast"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Criado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupBroadcast"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `idempotency_key_required`, `invalid_schedule`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`, `too_many_active_broadcasts`, `result_expired`"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`not_group_admin`, `group_not_found`, `no_admin_groups`"
          },
          "502": {
            "$ref": "#/components/responses/Error",
            "description": "`groups_unavailable`: o WhatsApp não respondeu a leitura dos grupos."
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`groups_not_ready`, `number_not_connected`, `engine_unavailable`"
          }
        }
      },
      "get": {
        "summary": "Listar envios para grupos",
        "operationId": "get-number-group-broadcasts",
        "description": "Escopo: `messages:read` (ou `campaigns:read`).",
        "tags": [
          "Lançamento em grupos"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "scheduled",
                "running",
                "paused",
                "paused_disconnected",
                "paused_by_safety",
                "completed",
                "canceled"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            },
            "description": "Valor de `next_cursor` da página anterior."
          }
        ],
        "responses": {
          "200": {
            "description": "Uma página de envios.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/GroupBroadcast"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/group-broadcasts/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Ler um envio para grupos",
        "operationId": "get-number-group-broadcasts-id",
        "description": "Com a contagem de grupos por situação. Escopo: `messages:read`.",
        "tags": [
          "Lançamento em grupos"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "responses": {
          "200": {
            "description": "O envio.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupBroadcast"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/group-broadcasts/{id}/report": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Resultado por grupo",
        "operationId": "get-number-group-broadcasts-id-report",
        "description": "Cada grupo do envio, na ordem: aceito, falhou (com `error_code`), pendente ou cancelado, e o estado da mensagem (`message_state`). Escopo: `messages:read`.",
        "tags": [
          "Lançamento em grupos"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "responses": {
          "200": {
            "description": "O envio com os grupos.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupBroadcastReport"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/group-broadcasts/{id}/pause": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Pausar envio para grupos",
        "operationId": "post-number-group-broadcasts-id-pause",
        "description": "Os grupos que faltam esperam até retomar. Escopo: `messages:send`.",
        "tags": [
          "Lançamento em grupos"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "responses": {
          "200": {
            "description": "Envio atualizado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupBroadcast"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_broadcast_state`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/group-broadcasts/{id}/resume": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Retomar envio para grupos",
        "operationId": "post-number-group-broadcasts-id-resume",
        "description": "Retoma também o pausado pela proteção (a contagem de falhas recomeça). Escopo: `messages:send`.",
        "tags": [
          "Lançamento em grupos"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "responses": {
          "200": {
            "description": "Envio atualizado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupBroadcast"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_broadcast_state`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/group-broadcasts/{id}/cancel": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Cancelar envio para grupos",
        "operationId": "post-number-group-broadcasts-id-cancel",
        "description": "Os grupos que faltam não recebem. Não tem volta. Escopo: `messages:send`.",
        "tags": [
          "Lançamento em grupos"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "responses": {
          "200": {
            "description": "Envio atualizado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/GroupBroadcast"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_broadcast_state`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/launch-links": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Criar link de lançamento",
        "operationId": "post-number-launch-links",
        "description": "Um link público `https://flowzap.flowpost.com.br/g/<slug>` (sem chave, sem login) que leva cada pessoa (302) ao convite do **primeiro grupo da lista com vaga** abaixo de `cap` (o WhatsApp aceita 1024 por grupo). As pessoas de cada grupo são lidas do WhatsApp no máximo a cada 2 minutos por link; entre uma leitura e outra, cada clique conta como uma pessoa a mais (no máximo 200 por grupo), para nenhum grupo passar do limite numa onda de acessos. Como clique não é entrada, quando os cliques fazem todos os grupos parecerem cheios o link continua levando ao último grupo com vaga pela contagem do WhatsApp. Visualizações de link (prévia do WhatsApp, redes sociais) não contam. Cliques são só um número por grupo: nada da pessoa nem o IP é guardado. A rota pública tem limite de acessos por IP (429; um endereço IPv6 conta pela sua rede /64).\n\nTodos os grupos precisam ser administrados pelo número (o link usa o convite de cada um): 422 `not_group_admin`. Com `auto_create`, quando a contagem do próprio WhatsApp diz que todos lotaram (nunca pelos cliques), o próximo grupo é criado sozinho. O `slug` é único para sempre (409 `slug_taken`). `Idempotency-Key` opcional.\n\nEscopo: `engine:write`.",
        "tags": [
          "Lançamento em grupos"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateLaunchLinkInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Repetição de um pedido já atendido (`Idempotent-Replay: true`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LaunchLink"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Criado, com os convites que chegaram em até 8 s.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LaunchLink"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_idempotency_key`, `invalid_image`, `image_too_large`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`slug_taken`, `idempotency_conflict`, `result_expired`"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`not_group_admin`, `group_not_found`, `media_integrity_failed`"
          },
          "502": {
            "$ref": "#/components/responses/Error",
            "description": "`groups_unavailable`"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`groups_not_ready`, `number_not_connected`, `engine_unavailable`"
          }
        }
      },
      "get": {
        "summary": "Listar links de lançamento",
        "operationId": "get-number-launch-links",
        "description": "Como estão guardados (sem ler o WhatsApp). Escopo: `engine:read`.",
        "tags": [
          "Lançamento em grupos"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            },
            "description": "Valor de `next_cursor` da página anterior."
          }
        ],
        "responses": {
          "200": {
            "description": "Uma página de links.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/LaunchLink"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/launch-links/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Ler um link de lançamento",
        "operationId": "get-number-launch-links-id",
        "description": "Aplica as contagens e os convites que já chegaram do WhatsApp. Ler o link nunca pede nada ao WhatsApp: as leituras novas, os convites e o grupo novo são pedidos pelos acessos ao link público. Escopo: `engine:read`.",
        "tags": [
          "Lançamento em grupos"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "O link.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LaunchLink"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "summary": "Alterar link de lançamento",
        "operationId": "put-number-launch-links-id",
        "description": "Nome, grupos (nova ordem; conferidos como na criação), `cap`, `active` e `auto_create`. O slug não muda. Escopo: `engine:write`.",
        "tags": [
          "Lançamento em grupos"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateLaunchLinkInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Link atualizado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LaunchLink"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_image`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`not_group_admin`, `group_not_found`"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`groups_not_ready`, `engine_unavailable`"
          }
        }
      },
      "delete": {
        "summary": "Apagar link de lançamento",
        "operationId": "delete-number-launch-links-id",
        "description": "O endereço público para de funcionar (404) e o slug nunca é reaproveitado. Escopo: `engine:write`.",
        "tags": [
          "Lançamento em grupos"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "responses": {
          "204": {
            "description": "Apagado."
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/campaigns": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "summary": "Criar campanha",
        "operationId": "post-number-campaigns",
        "description": "Envio em massa **só para quem deu consentimento** (lead com `opted_in` e sem opt-out): uma lista de telefones ou uma etiqueta do CRM. Públicos coletados de grupos nunca são destinatários. Até 5000 destinatários, 10 campanhas ativas por número, pausa aleatória de 3 s a 10 min entre envios. Exige `Idempotency-Key`. Se algum destinatário não tiver consentimento, responde 422 `consent_required` com `rejected` e `total` no erro, a menos que `skip_unconsented` seja true.\n\nRecursos: `variants` (2 a 5 textos alternados por destinatário), personalização com `{{nome}}`, `{{primeiro_nome}}` e `{{campo:<chave>}}` (com alternativo: `{{nome|cliente}}`; marcador inválido responde 422 `invalid_placeholder` com `placeholder` no erro), `daily_limit` por número (padrão 200, dia de Brasília, somando as campanhas do número), `window` (dias e horário de envio) e pausa automática `paused_by_safety` quando mais de 20% dos últimos 50 envios falham ou quando o WhatsApp limita conversas novas do número. Quem pede para sair é pulado mesmo depois de criada a campanha.\n\nEscopo: `messages:send`.",
        "tags": [
          "Campanhas"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCampaignInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Repetição de um pedido já atendido (`Idempotent-Replay: true`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Campaign"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Criada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Campaign"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `idempotency_key_required`, `invalid_schedule`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`idempotency_conflict`, `too_many_active_campaigns`"
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`consent_required`, `no_consented_recipients`, `too_many_recipients`, `unknown_tag`, `invalid_placeholder`"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`"
          }
        }
      },
      "get": {
        "summary": "Listar campanhas",
        "operationId": "get-number-campaigns",
        "description": "Escopo: `messages:read`.",
        "tags": [
          "Campanhas"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "scheduled",
                "running",
                "paused",
                "paused_disconnected",
                "paused_by_safety",
                "completed",
                "canceled"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            },
            "description": "Valor de `next_cursor` da página anterior."
          }
        ],
        "responses": {
          "200": {
            "description": "Uma página de campanhas.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Campaign"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/campaigns/summary": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Painel de campanhas do número",
        "operationId": "get-number-campaigns-summary",
        "description": "Envios de hoje contra o limite diário (dia de Brasília), campanhas por estado, métricas dos envios feitos nos últimos `days` dias (enviados, entregues, lidos, falhas, respostas e saídas) com série por dia, e as campanhas pausadas por segurança.\n\nEscopo: `messages:read`.",
        "tags": [
          "Campanhas"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 90,
              "default": 7
            }
          }
        ],
        "responses": {
          "200": {
            "description": "O painel.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CampaignSummary"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/campaigns/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Ler campanha e contagens",
        "operationId": "get-number-campaigns-id",
        "description": "Escopo: `messages:read`.",
        "tags": [
          "Campanhas"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "responses": {
          "200": {
            "description": "A campanha.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Campaign"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/campaigns/{id}/cancel": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Cancelar campanha",
        "operationId": "post-number-campaigns-id-cancel",
        "description": "Escopo: `messages:send`.",
        "tags": [
          "Campanhas"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "responses": {
          "200": {
            "description": "Campanha atualizada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Campaign"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_campaign_state`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/campaigns/{id}/pause": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Pausar campanha",
        "operationId": "post-number-campaigns-id-pause",
        "description": "Escopo: `messages:send`.",
        "tags": [
          "Campanhas"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "responses": {
          "200": {
            "description": "Campanha atualizada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Campaign"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_campaign_state`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/campaigns/{id}/recipients": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Destinatários e resultado",
        "operationId": "get-number-campaigns-id-recipients",
        "description": "Escopo: `messages:read`.",
        "tags": [
          "Campanhas"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "accepted",
                "skipped",
                "failed",
                "canceled"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            },
            "description": "Valor de `next_cursor` da página anterior."
          }
        ],
        "responses": {
          "200": {
            "description": "Uma página de destinatários.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CampaignRecipient"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `invalid_cursor`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/campaigns/{id}/report": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Painel da campanha",
        "operationId": "get-number-campaigns-id-report",
        "description": "Série por hora ou por dia (America/Sao_Paulo) de enviados, entregues, lidos, falhas, respostas e saídas, com os totais. Cada métrica conta pela hora do próprio evento (entrega, leitura, resposta, saída).\n\nEscopo: `messages:read`.",
        "tags": [
          "Campanhas"
        ],
        "x-scopes": [
          "messages:read"
        ],
        "parameters": [
          {
            "name": "bucket",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "hour",
                "day"
              ],
              "default": "hour"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "O painel.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CampaignReport"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/campaigns/{id}/resume": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID do recurso.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "summary": "Retomar campanha",
        "operationId": "post-number-campaigns-id-resume",
        "description": "Retoma uma campanha pausada (também `paused_by_safety`; a janela de falhas recomeça). Escopo: `messages:send`.",
        "tags": [
          "Campanhas"
        ],
        "x-scopes": [
          "messages:send"
        ],
        "responses": {
          "200": {
            "description": "Campanha atualizada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Campaign"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_campaign_state`"
          }
        }
      }
    },
    "/v1/chatwoot/hooks/{token}": {
      "parameters": [
        {
          "name": "token",
          "in": "path",
          "required": true,
          "description": "Token secreto da integração, gerado pelo FlowZap.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "Webhook chamado pelo Chatwoot",
        "operationId": "post-v1-chatwoot-hooks-token",
        "description": "**Sem chave de API.** O Chatwoot chama este endereço (o `webhook_url` da configuração); o token de 256 bits no caminho identifica o número. Só respostas enviadas por atendentes (não notas privadas) viram mensagem no WhatsApp. Limite: 600 pedidos por minuto por endereço de origem e 300 por token.\n\nSem autenticação por chave de API.",
        "tags": [
          "Chatwoot, n8n e Make"
        ],
        "x-scopes": [],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          },
          "description": "Evento do Chatwoot, como ele envia."
        },
        "responses": {
          "200": {
            "description": "Ignorado (`status: ignored`, com o motivo).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ChatwootHookResult"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Enviado para a fila (`status: sent`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ChatwootHookResult"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_payload`"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Error",
            "description": "`numbers_over_limit`: envio da conta pausado por ter mais números do que o plano permite."
          },
          "422": {
            "$ref": "#/components/responses/Error",
            "description": "`recipient_unknown`"
          },
          "429": {
            "$ref": "#/components/responses/Error",
            "description": "`rate_limited`"
          },
          "503": {
            "$ref": "#/components/responses/Error",
            "description": "`engine_unavailable`, `send_unavailable`"
          }
        }
      }
    },
    "/v1/workspaces/{workspaceId}/instances/{instanceId}/chatwoot": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WorkspaceId"
        },
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "summary": "Ler integração com o Chatwoot",
        "operationId": "get-number-chatwoot",
        "description": "Escopo: `engine:read`.",
        "tags": [
          "Chatwoot, n8n e Make"
        ],
        "x-scopes": [
          "engine:read"
        ],
        "responses": {
          "200": {
            "description": "Configuração (token mascarado) e `webhook_url` para colar no Chatwoot.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ChatwootConfig"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "summary": "Ligar ou alterar integração com o Chatwoot",
        "operationId": "put-number-chatwoot",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Chatwoot, n8n e Make"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatwootConfigInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Salva.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ChatwootConfig"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error",
            "description": "`invalid_input`, `chatwoot_url_invalid`, `api_access_token_required`"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "summary": "Remover integração com o Chatwoot",
        "operationId": "delete-number-chatwoot",
        "description": "Escopo: `engine:write`.",
        "tags": [
          "Chatwoot, n8n e Make"
        ],
        "x-scopes": [
          "engine:write"
        ],
        "responses": {
          "204": {
            "description": "Feito, sem corpo."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ScopeDenied"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "webhooks": {
    "evento": {
      "post": {
        "summary": "Aviso de evento (webhook)",
        "description": "O FlowZap faz `POST` no endereço cadastrado em `POST /v1/webhook-endpoints` a cada evento. O corpo traz só o tipo e os IDs; leia o conteúdo pela API com a sua chave.\n\n## Assinatura\nCabeçalhos: `X-Flow-Timestamp` (segundos Unix), `X-Flow-Event-Id` e `X-Flow-Signature: v1:<secret_kid>:<hex>`, onde `<hex>` é o HMAC-SHA256, com o `secret` do cadastro, de `<timestamp>.<event_id>.<corpo exato em bytes>`. Recuse diferença de relógio maior que 5 minutos e compare em tempo constante. Nas 24 h depois de `POST /v1/webhook-endpoints/{id}/rotate-secret`, o cabeçalho traz dois valores separados por vírgula (segredo novo e anterior); aceite se qualquer um conferir.\n\n## Entrega\nResponda 2xx em até 15 segundos; qualquer 2xx confirma. Sem confirmação, novas tentativas em 10 s, 30 s, 2 min, 10 min, 1 h, 6 h e 24 h (no máximo 8, respeitando `Retry-After`). 410 desativa o endereço; 401/403 três vezes o pausa; outros 4xx (exceto 408 e 429) e redirecionamentos não são repetidos. O mesmo `event_id` pode chegar mais de uma vez: trate avisos repetidos. O histórico fica em `GET /v1/webhook-deliveries`.\n\n**Filtros.** Cada endereço pode receber só alguns tipos (`event_types`) e/ou só alguns números (`instance_ids`); sem filtro, recebe tudo da área de trabalho. Mude em `PATCH /v1/webhook-endpoints/{id}`. **Pausa sem perda.** Endereço `paused` (por você, ou pelo FlowZap após 401/403 três vezes ou destino bloqueado) guarda os avisos novos como `held` (até 10.000 por endereço; além disso o aviso não é guardado para esse endereço); ao reativar (`state: active`), os dos últimos 7 dias são entregues e os mais antigos terminam `dead` (`held_expired`). **Teste.** `POST /v1/webhook-endpoints/{id}/ping` envia agora um aviso `webhook.ping` assinado (não guardado; `instance_id: null`, `sequence: 0`) e responde se o seu endereço aceitou. **Reenvio.** `POST /v1/webhook-deliveries/{id}/retry` reenvia uma entrega `delivered` ou `dead` (mesmo `event_id`, nova rodada; até 10). O histórico (`GET /v1/webhook-deliveries`) filtra por endereço, estado, tipo e data, com `cursor`.\n\n## Ordem, duplicidade e retenção\nNão há ordem global: cada número tem a sua sequência (`sequence`, crescente). Ordene por `sequence` dentro do número e trate cada `event_id` uma vez (webhook, SSE e reenvio podem repetir). Para retomar depois de uma queda: `Last-Event-ID` (ou `last_event_id`, ou `cursor=map` para várias contas) no SSE, ou `GET …/events?after_sequence=` por número. Os eventos ficam disponíveis por pelo menos 90 dias; hoje nada é apagado antes da exclusão da conta, e uma limpeza automática só será ligada com aviso no changelog.\n\n## Catálogo\n| Evento | Quando | `resource_id` |\n|---|---|---|\n| `message.queued` | envio aceito na fila | envio: `GET /v1/messages/{id}` |\n| `message.dispatching` | o número começou a enviar | envio |\n| `message.provider_accepted` | o WhatsApp aceitou | envio |\n| `message.delivered` | entregue no aparelho | envio |\n| `message.read` | lida | envio |\n| `message.failed` | falhou | envio |\n| `message.unknown` | resultado incerto: confira antes de reenviar | envio |\n| `message.expired` | passou de `expires_at` sem sair | envio |\n| `message.canceled` | cancelado na fila | envio |\n| `message.receipt` | recibo que não muda o estado; em grupo, no máximo um por mensagem a cada 60 s (a contagem está em `GET /v1/messages/{id}/receipts`) | envio |\n| `message.received` | mensagem recebida | `GET …/inbound/{id}` |\n| `instance.paired` | número pareado ao WhatsApp | número |\n| `instance.connection` | evento do motor | `GET /v1/events/{id}` |\n| `instance.reachout_timelock` | aviso do WhatsApp de que o número não pode iniciar conversas novas até `ends_at` (`active`, `enforcement_type`, `ends_at`); estado em `GET …/limits` | `GET /v1/events/{id}` |\n| `presence.update` | evento do motor | `GET /v1/events/{id}` |\n| `chat.presence` | evento do motor | `GET /v1/events/{id}` |\n| `group.update` | evento do motor | `GET /v1/events/{id}` |\n| `group.joined` | evento do motor | `GET /v1/events/{id}` |\n| `contact.picture` | evento do motor | `GET /v1/events/{id}` |\n| `contact.update` | evento do motor | `GET /v1/events/{id}` |\n| `contact.blocklist` | evento do motor | `GET /v1/events/{id}` |\n| `call.offer` | evento do motor | `GET /v1/events/{id}` |\n| `call.accept` | evento do motor | `GET /v1/events/{id}` |\n| `call.terminate` | evento do motor | `GET /v1/events/{id}` |\n| `call.reject` | evento do motor | `GET /v1/events/{id}` |\n| `call.started` | (beta) ligação do módulo de ligações começou: `call_id`, `direction` (`outbound`/`inbound`), `to` ou `from`; `media_session_id` quando o áudio passa pelo navegador | `GET /v1/events/{id}` |\n| `call.answered` | (beta) ligação atendida: `call_id`; `media_session_id` quando o áudio passa pelo navegador; `recording` (a ligação está sendo gravada), `notice_played` (sempre `false` aqui) e `recording_id` quando grava | `GET /v1/events/{id}` |\n| `call.media_connected` | (beta) a voz da ligação ao vivo conectou: o WhatsApp atendeu, o WebSocket de áudio do navegador/integração estava conectado e o primeiro áudio chegou (uma vez por ligação): `call_id`, `direction`, `media_session_id`. Ligação de teste, atendida no celular ou sem áudio conectado nunca o emite; aparece também em `audio_connected_at` de `GET …/calls/{id}` | `GET /v1/events/{id}` |\n| `call.ringing` | (beta) ligação recebida de um número permitido, tocando à espera de alguém atender pelo console (não é atendida automaticamente): `call_id`, `direction` (`inbound`), `from` | `GET /v1/events/{id}` |\n| `call.ended` | (beta) ligação encerrada: `call_id`, `direction`, `duration_ms`, `answered`, `inbound_audio_dbfs` (nível do áudio recebido, ou `null`), `reason`, `answered_in` (`browser`, `phone` ou `null`), `media_session_id` (quando o áudio passou pelo navegador), `recording` (foi gravada), `notice_played` (o aviso de gravação tocou inteiro; `false` também quando a ligação dispensou o aviso) e `recording_id` quando gravou. `reason`: `completed`, `no_answer`, `declined`, `cancelled`, `peer_hangup`, `media_timeout`, `failed`, `worker_stopping` e, com atendimento pelo console, `missed` (ninguém atendeu em 45 s e quem ligou desistiu), `declined_by_agent`, `hangup_by_agent`, `media_failed` (o áudio com o navegador falhou) | `GET /v1/events/{id}` |\n| `label.edit` | evento do motor | `GET /v1/events/{id}` |\n| `label.chat` | evento do motor | `GET /v1/events/{id}` |\n| `label.message` | evento do motor | `GET /v1/events/{id}` |\n| `chat.update` | evento do motor | `GET /v1/events/{id}` |\n| `history.sync` | evento do motor | `GET /v1/events/{id}` |\n| `newsletter.join` | evento do motor | `GET /v1/events/{id}` |\n| `newsletter.leave` | evento do motor | `GET /v1/events/{id}` |\n| `newsletter.mute_change` | evento do motor | `GET /v1/events/{id}` |\n| `newsletter.live_update` | evento do motor | `GET /v1/events/{id}` |\n| `ticket.opened` | atendimento aberto por mensagem recebida de quem não tinha atendimento aberto, ou à mão (`POST …/tickets`, inclusive de grupo) | atendimento: `GET …/tickets/{id}` |\n| `ticket.resolved` | atendimento resolvido | atendimento |\n| `ticket.reopened` | atendimento reaberto | atendimento |\n| `ticket.assigned` | responsável do atendimento mudou | atendimento |\n| `ticket.pending_set` | atendimento marcado como pendente (ou nível/observação da pendência mudou) | atendimento (`pending`) |\n| `ticket.pending_cleared` | pendência do atendimento retirada | atendimento |\n| `lead.stage_changed` | contato entrou no funil ou mudou de etapa | lead (`stage_id` em `GET …/crm/pipeline` ou no lead) |\n| `csat.answered` | cliente respondeu a pesquisa de satisfação | atendimento (`csat.score`) |\n| `call.recording_ready` | gravação de uma ligação pronta para baixar | ligação: `GET …/calls/{id}` (o áudio em `GET …/calls/{id}/recording`, escopo `calls:recordings`) |\n| `call.recording_deleted` | gravação apagada (fim do prazo, módulo removido, pelo console ou pela API; motivo em `recording.deleted_reason`) | ligação: `GET …/calls/{id}` |\n| `call.recording_failed` | gravação terminou sem arquivo (a pessoa desligou durante o aviso, sem áudio, não fechou ou a conversão falhou); o motivo está em `recording.failure_reason` | ligação: `GET …/calls/{id}` |\n\nNovos em outubro de 2026: `ticket.opened`, `ticket.resolved`, `ticket.reopened`, `ticket.assigned`, `ticket.pending_set`, `ticket.pending_cleared`, `lead.stage_changed` e `csat.answered`. Todo endereço cadastrado sem filtro passa a recebê-los (use `event_types` para receber só o que interessa); ignore os tipos que a sua integração não usa. O conteúdo de `ticket.*`, `lead.stage_changed`, `csat.answered` e `call.recording_*` também sai em `GET /v1/events/{id}` (pelo `event_id`).",
        "operationId": "webhook-event",
        "x-event-types": [
          "message.queued",
          "message.dispatching",
          "message.provider_accepted",
          "message.delivered",
          "message.read",
          "message.failed",
          "message.unknown",
          "message.expired",
          "message.receipt",
          "message.received",
          "message.canceled",
          "instance.paired",
          "instance.connection",
          "instance.reachout_timelock",
          "presence.update",
          "chat.presence",
          "group.update",
          "group.joined",
          "contact.picture",
          "contact.update",
          "contact.blocklist",
          "call.offer",
          "call.accept",
          "call.terminate",
          "call.reject",
          "call.started",
          "call.ringing",
          "call.answered",
          "call.media_connected",
          "call.ended",
          "label.edit",
          "label.chat",
          "label.message",
          "chat.update",
          "history.sync",
          "newsletter.join",
          "newsletter.leave",
          "newsletter.mute_change",
          "newsletter.live_update",
          "ticket.opened",
          "ticket.resolved",
          "ticket.reopened",
          "ticket.assigned",
          "ticket.pending_set",
          "ticket.pending_cleared",
          "lead.stage_changed",
          "csat.answered",
          "call.recording_ready",
          "call.recording_deleted",
          "call.recording_failed"
        ],
        "parameters": [
          {
            "name": "X-Flow-Timestamp",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^\\d{10,11}$"
            }
          },
          {
            "name": "X-Flow-Event-Id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "X-Flow-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^v1:[0-9a-f-]{36}:[0-9a-f]{64}(,v1:[0-9a-f-]{36}:[0-9a-f]{64})?$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEvent"
                  },
                  {
                    "$ref": "#/components/schemas/WebhookPingBody"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Qualquer 2xx confirma a entrega."
          },
          "410": {
            "description": "Desativa este endereço."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ActorLabel": {
        "type": "string",
        "minLength": 1,
        "maxLength": 80,
        "description": "Opcional: nome do atendente externo que enviou (espaços nas pontas removidos). Gravado com o envio, volta em `GET /v1/messages/{id}`; não é conteúdo nem entra na idempotência."
      },
      "Audience": {
        "type": "object",
        "required": [
          "id",
          "name",
          "state",
          "error_code",
          "selection",
          "member_count",
          "admin_member_count",
          "participants_without_phone",
          "missing_group_jids",
          "created_at",
          "collect_requested_at",
          "refreshed_at",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "collecting",
              "ready",
              "failed",
              "expired"
            ],
            "description": "`collecting`: lendo os grupos (consulte de novo). `failed`: a última coleta falhou (`error_code`); os membros da coleta anterior continuam. `expired`: 180 dias sem atualizar; os membros foram apagados."
          },
          "error_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "selection": {
            "type": "object",
            "required": [
              "all",
              "group_jids"
            ],
            "properties": {
              "all": {
                "type": "boolean"
              },
              "group_jids": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "member_count": {
            "type": "integer",
            "description": "Pessoas com telefone, sem repetir, sem o próprio número."
          },
          "admin_member_count": {
            "type": "integer",
            "description": "Das quais estão em algum grupo que o número administra (informativo; todas vão para o Meta, o Google e a planilha)."
          },
          "participants_without_phone": {
            "type": "integer",
            "description": "Participantes que o WhatsApp mostrou sem telefone (só o identificador oculto); não entram no público."
          },
          "missing_group_jids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Grupos pedidos em que o número não está mais."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "collect_requested_at": {
            "type": "string",
            "format": "date-time"
          },
          "refreshed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Data em que os membros são apagados se o público não for atualizado (180 dias após a última coleta)."
          }
        }
      },
      "AudienceDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Audience"
          },
          {
            "type": "object",
            "required": [
              "next_collection_at",
              "sources",
              "export_declaration",
              "export_declarations"
            ],
            "properties": {
              "next_collection_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "A partir de quando o número pode coletar de novo (uma coleta a cada 10 minutos por número)."
              },
              "sources": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "group_jid",
                    "group_name",
                    "is_admin",
                    "collected_at",
                    "participants_seen",
                    "phones_resolved"
                  ],
                  "properties": {
                    "group_jid": {
                      "type": "string"
                    },
                    "group_name": {
                      "type": "string"
                    },
                    "is_admin": {
                      "type": "boolean"
                    },
                    "collected_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "participants_seen": {
                      "type": "integer"
                    },
                    "phones_resolved": {
                      "type": "integer"
                    }
                  }
                }
              },
              "export_declaration": {
                "$ref": "#/components/schemas/ExportDeclaration",
                "description": "Declaração dos arquivos de anúncios (Meta e Google); mantida por compatibilidade, igual a `export_declarations.meta`."
              },
              "export_declarations": {
                "type": "object",
                "description": "A declaração que cada formato exige em `POST …/exports`.",
                "required": [
                  "meta",
                  "google",
                  "csv"
                ],
                "properties": {
                  "meta": {
                    "$ref": "#/components/schemas/ExportDeclaration"
                  },
                  "google": {
                    "$ref": "#/components/schemas/ExportDeclaration"
                  },
                  "csv": {
                    "$ref": "#/components/schemas/ExportDeclaration"
                  }
                }
              }
            }
          }
        ]
      },
      "AudienceExport": {
        "type": "object",
        "required": [
          "id",
          "format",
          "rows",
          "declared_by",
          "declaration_text_version",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "format": {
            "type": "string",
            "enum": [
              "meta",
              "google",
              "csv"
            ]
          },
          "rows": {
            "type": "integer"
          },
          "declared_by": {
            "type": "object",
            "required": [
              "kind",
              "id"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "api_key",
                  "user"
                ]
              },
              "id": {
                "type": "string"
              }
            }
          },
          "declaration_text_version": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AudienceMember": {
        "type": "object",
        "required": [
          "phone",
          "name",
          "group_jids",
          "from_admin_group",
          "first_seen_at",
          "last_seen_at"
        ],
        "properties": {
          "phone": {
            "type": "string",
            "description": "Mascarado (`+5511*****4321`), ou completo com `full=1` (escopo `audiences:export`)."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Nome mostrado no grupo; só com `full=1`."
          },
          "group_jids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "from_admin_group": {
            "type": "boolean"
          },
          "first_seen_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_seen_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AutoCreateInput": {
        "type": "object",
        "required": [
          "enabled",
          "name",
          "phones"
        ],
        "description": "Grupo novo quando todos lotam: `<name> <número>` (ex.: “Lançamento 7”), com a descrição, só administradores mandando mensagem (padrão) e entrada sem aprovação. Só a contagem do WhatsApp (nunca os cliques) dispara a criação. Um resultado incerto do WhatsApp para a criação desliga a criação automática (`auto_create.error: create_uncertain`) em vez de criar outro grupo; passar de 3 grupos criados numa hora ou 20 num dia também (`auto_create_limit`). Ligar de novo libera.",
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 90
          },
          "description": {
            "type": "string",
            "maxLength": 2048
          },
          "only_admins_send": {
            "type": "boolean",
            "default": true
          },
          "phones": {
            "type": "array",
            "minItems": 1,
            "maxItems": 5,
            "items": {
              "$ref": "#/components/schemas/E164"
            },
            "description": "O WhatsApp só cria grupo com mais uma pessoa: um telefone da equipe. Fica cifrado e nunca volta nas respostas."
          },
          "image_media_id": {
            "type": "string",
            "format": "uuid",
            "description": "Foto do grupo: um JPEG enviado antes (`POST …/media?kind=image`), copiado para o link."
          },
          "next_sequence": {
            "type": "integer",
            "minimum": 1,
            "description": "Número do próximo grupo (padrão: quantidade de grupos + 1)."
          }
        },
        "additionalProperties": false
      },
      "AutoReplies": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AutoRepliesInput"
          },
          {
            "type": "object",
            "required": [
              "updated_at",
              "updated_by"
            ],
            "properties": {
              "updated_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "`null`: o número ainda usa os padrões."
              },
              "updated_by": {
                "type": [
                  "object",
                  "null"
                ],
                "required": [
                  "id",
                  "name"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "description": "Quem salvou por último (a chave age por quem a criou; `null` sem pessoa)."
              }
            }
          }
        ]
      },
      "AutoRepliesInput": {
        "type": "object",
        "description": "Configuração completa das respostas automáticas de um número. O PUT substitui tudo (não é merge); `updated_at` e `updated_by` do GET podem voltar no corpo e são ignorados.",
        "required": [
          "enabled",
          "welcome",
          "away",
          "menu",
          "keywords",
          "pause_minutes_after_human",
          "auto_create_lead",
          "csat"
        ],
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "Liga ou desliga todas as respostas automáticas (a pesquisa de satisfação tem o próprio interruptor)."
          },
          "welcome": {
            "type": "object",
            "required": [
              "enabled",
              "text",
              "cooldown_hours"
            ],
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "text": {
                "type": "string",
                "maxLength": 1000,
                "description": "Obrigatório (1 a 1000 caracteres) quando ligado. Com o menu ligado, as opções vão na mesma mensagem."
              },
              "cooldown_hours": {
                "type": "integer",
                "minimum": 1,
                "maximum": 720,
                "default": 24,
                "description": "Boas-vindas de novo para o mesmo contato só depois deste intervalo."
              }
            },
            "additionalProperties": false
          },
          "away": {
            "type": "object",
            "required": [
              "enabled",
              "text",
              "hours",
              "cooldown_hours"
            ],
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "text": {
                "type": "string",
                "maxLength": 1000,
                "description": "Obrigatório quando ligado. Enviado fora do horário de atendimento."
              },
              "hours": {
                "$ref": "#/components/schemas/BusinessHours"
              },
              "cooldown_hours": {
                "type": "integer",
                "minimum": 1,
                "maximum": 720,
                "default": 12
              }
            },
            "additionalProperties": false
          },
          "menu": {
            "type": "object",
            "required": [
              "enabled",
              "text",
              "options"
            ],
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "Ligado exige ao menos uma opção."
              },
              "text": {
                "type": "string",
                "maxLength": 1000,
                "description": "Introdução do menu; obrigatória quando ligado."
              },
              "options": {
                "type": "array",
                "maxItems": 9,
                "items": {
                  "$ref": "#/components/schemas/AutoReplyOption"
                }
              }
            },
            "additionalProperties": false
          },
          "keywords": {
            "type": "array",
            "maxItems": 30,
            "items": {
              "$ref": "#/components/schemas/AutoReplyKeyword"
            },
            "description": "Vale a primeira regra que casa (sem acento, maiúsculas ou pontuação)."
          },
          "pause_minutes_after_human": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10080,
            "default": 120,
            "description": "Depois que alguém da equipe responde (console, Chatwoot ou o celular do número), nada automático para esse contato por este tempo. 0 desliga a pausa."
          },
          "auto_create_lead": {
            "type": "boolean",
            "default": true,
            "description": "Quem escreve entra no funil, na primeira etapa, sem consentimento para campanhas (um contato existente nunca é sobrescrito). Ligado, um contato apagado volta ao funil na próxima mensagem que mandar."
          },
          "csat": {
            "type": "object",
            "required": [
              "enabled",
              "text",
              "thanks_text"
            ],
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "Envia a pesquisa ao resolver um atendimento (dentro de 24 h da última mensagem do contato)."
              },
              "text": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              },
              "thanks_text": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "AutoReplyKeyword": {
        "type": "object",
        "required": [
          "match",
          "terms",
          "reply"
        ],
        "properties": {
          "match": {
            "type": "string",
            "enum": [
              "contains",
              "exact"
            ],
            "description": "`contains`: a mensagem tem o termo como palavra(s) inteira(s); `exact`: a mensagem é só o termo."
          },
          "terms": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40
            }
          },
          "reply": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1000
          }
        },
        "additionalProperties": false
      },
      "AutoReplyOption": {
        "type": "object",
        "required": [
          "key",
          "label",
          "reply"
        ],
        "properties": {
          "key": {
            "type": "string",
            "enum": [
              "1",
              "2",
              "3",
              "4",
              "5",
              "6",
              "7",
              "8",
              "9"
            ],
            "description": "O que o cliente digita; único no menu."
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "reply": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1000
          },
          "stage_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Move o contato para esta etapa do funil."
          },
          "tag_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Põe esta etiqueta no contato."
          },
          "assign_user_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Pessoa da equipe que vira responsável pelo contato e pelo atendimento aberto."
          }
        },
        "additionalProperties": false
      },
      "BusinessHours": {
        "type": "object",
        "required": [
          "days",
          "start",
          "end",
          "tz"
        ],
        "properties": {
          "days": {
            "type": "array",
            "minItems": 1,
            "maxItems": 7,
            "uniqueItems": true,
            "items": {
              "type": "integer",
              "minimum": 1,
              "maximum": 7
            },
            "description": "Dias de atendimento: 1 = segunda … 7 = domingo."
          },
          "start": {
            "type": "string",
            "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$",
            "description": "Início, HH:MM (incluído)."
          },
          "end": {
            "type": "string",
            "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$",
            "description": "Fim, HH:MM (excluído); depois do início."
          },
          "tz": {
            "type": "string",
            "description": "Fuso horário IANA, ex.: `America/Sao_Paulo`."
          }
        },
        "additionalProperties": false
      },
      "BusinessProfile": {
        "type": "object",
        "required": [
          "jid",
          "address",
          "email",
          "categories",
          "profile_options",
          "business_hours"
        ],
        "properties": {
          "jid": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "name"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "profile_options": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "business_hours": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "timezone",
              "days"
            ],
            "properties": {
              "timezone": {
                "type": "string"
              },
              "days": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "day_of_week",
                    "mode",
                    "open_time",
                    "close_time"
                  ],
                  "properties": {
                    "day_of_week": {
                      "type": "string"
                    },
                    "mode": {
                      "type": "string"
                    },
                    "open_time": {
                      "type": "string"
                    },
                    "close_time": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "Call": {
        "type": "object",
        "required": [
          "id",
          "call_id",
          "workspace_id",
          "instance_id",
          "direction",
          "phone",
          "missed",
          "answered",
          "answered_in",
          "via",
          "user_id",
          "user_name",
          "actor_label",
          "ended_by_label",
          "state",
          "ended_by",
          "requested_at",
          "started_at",
          "answered_at",
          "audio_connected_at",
          "ended_at",
          "duration_ms",
          "wait_duration_ms",
          "talk_duration_ms",
          "reason",
          "media_session_id",
          "lead_id",
          "recording_state",
          "recording"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Id da ligação no histórico (`resource_id` dos webhooks `call.recording_ready` e `call.recording_deleted`)."
          },
          "call_id": {
            "type": "string",
            "description": "ID da chamada no WhatsApp (eventos `call.*`)."
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "instance_id": {
            "type": "string",
            "format": "uuid"
          },
          "direction": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "inbound",
              "outbound",
              null
            ]
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Telefone da outra pessoa (E.164); `null` quando o WhatsApp não informou o número."
          },
          "missed": {
            "type": "boolean",
            "description": "Recebida e não atendida."
          },
          "answered": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "`null`: a ligação só tocou no celular e o WhatsApp não informou se foi atendida."
          },
          "answered_in": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "browser",
              "phone",
              null
            ]
          },
          "via": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "console",
              "api",
              "phone",
              null
            ],
            "description": "Por onde foi atendida ou feita: console (uma pessoa da equipe), api (uma chave), phone (no celular)."
          },
          "user_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Pessoa da equipe que atendeu (recebida) ou fez (feita) a ligação pelo console."
          },
          "user_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "actor_label": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 80,
            "description": "Atendente do seu sistema que fez (`POST …/calls`) ou atendeu (`…/answer`) a ligação pela API, como enviado em `actor_label` (declarado, não verificado). `null` pelo console (veja `user_id`) ou sem `actor_label`."
          },
          "ended_by_label": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 80,
            "description": "Atendente do seu sistema que recusou (`…/decline`) ou desligou (`…/hangup`) a ligação pela API, como enviado em `actor_label`; só quando foi esse pedido que encerrou a ligação (`ended_by: agent`)."
          },
          "state": {
            "type": "string",
            "enum": [
              "ringing",
              "answered",
              "in_progress",
              "completed",
              "missed",
              "no_answer",
              "declined",
              "cancelled",
              "failed",
              "ended"
            ],
            "description": "Situação da ligação, calculada a partir do histórico:\n- `ringing`: chamando (feita) ou tocando (recebida), sem atendimento ainda;\n- `answered`: o WhatsApp atendeu, a voz ainda não conectou (ou foi atendida no celular);\n- `in_progress`: a voz conectou (`audio_connected_at`, evento `call.media_connected`);\n- `completed`: atendida e encerrada (`reason` `completed`, `peer_hangup` ou `hangup_by_agent` depois do atendimento);\n- `missed`: recebida e ninguém atendeu (`missed`);\n- `no_answer`: feita e a pessoa não atendeu a tempo (`no_answer`);\n- `declined`: recusada — pela pessoa (`declined`, feita; o WhatsApp não distingue ocupado: um contato ocupado também aparece assim), pelo atendente (`declined_by_agent`) ou no celular (`rejected`);\n- `cancelled`: o atendente desligou antes de a pessoa atender (`hangup_by_agent` sem atendimento) ou quem ligou desistiu antes do atendimento automático (`cancelled`);\n- `failed`: falhou (`failed`, `media_failed`, `media_timeout`, `worker_stopping`);\n- `ended`: terminou e o FlowZap não sabe como (ligação só do celular sem atendimento informado, ou sem o fim depois de 10 minutos tocando ou 3 horas atendida).\n\nAntes de a ligação aparecer no histórico (logo depois de `POST …/calls`), acompanhe a operação em `GET /v1/operations/{id}`."
          },
          "ended_by": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "agent",
              "contact",
              "system",
              null
            ],
            "description": "Quem encerrou: `agent` (o atendente: `hangup_by_agent`, `declined_by_agent`), `contact` (a outra pessoa: `peer_hangup`, `declined`, `cancelled`) ou `system` (o FlowZap: `no_answer`, `completed` da ligação de teste, falhas). `null` enquanto não termina e quando não se sabe (`missed`: a pessoa pode ter desistido ou o tempo de toque acabou; atendida em outro aparelho; ligações só do celular)."
          },
          "requested_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Ligação ao vivo feita pelo FlowZap (`POST …/calls` com `audio`, ou pelo console): quando foi pedida. `null` nas recebidas e na ligação de teste."
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "description": "Início: a oferta enviada (feita) ou a chamada recebida (UTC)."
          },
          "answered_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "audio_connected_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Quando a voz conectou: o WhatsApp atendeu, o seu WebSocket de áudio estava conectado e o primeiro áudio chegou (evento `call.media_connected`). `null` se não conectou, na ligação de teste e nas atendidas no celular."
          },
          "ended_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "duration_ms": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Ligações pelo FlowZap: do início (`started_at`) ao fim, **com o tempo de toque** — o mesmo `duration_ms` de `call.ended`. Ligações só do celular: do atendimento ao fim (0 sem atendimento). Para separar espera de conversa, use `wait_duration_ms` e `talk_duration_ms`."
          },
          "wait_duration_ms": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Espera: do início ao atendimento; sem atendimento, do início ao fim. `null` enquanto toca."
          },
          "talk_duration_ms": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Conversa: do atendimento ao fim. `null` sem atendimento ou enquanto não termina."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Motivo do fim, como em `call.ended` (`completed`, `missed`, `hangup_by_agent`…); `rejected` ou o motivo do WhatsApp para ligações só do celular. Veja `state` e `ended_by`."
          },
          "media_session_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "lead_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Contato do CRM deste telefone no número, quando existe."
          },
          "recording_state": {
            "type": "string",
            "enum": [
              "none",
              "recording",
              "processing",
              "ready",
              "failed",
              "deleted",
              "skipped_quota",
              "skipped_off"
            ],
            "description": "`skipped_off`: a gravação estava desligada; `skipped_quota`: a conta estava no limite de espaço (10 GiB); `none`: ligação sem áudio pelo FlowZap."
          },
          "recording": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/CallRecording"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "additionalProperties": false,
        "example": {
          "id": "2f8d6c1a-7b3e-4a59-9c0d-1e2f3a4b5c6d",
          "call_id": "3EB0C0FFEE0123456789ABCDEF0A0B0C",
          "workspace_id": "5b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
          "instance_id": "7a8b9c0d-1e2f-4a3b-9c4d-5e6f7a8b9c0d",
          "direction": "outbound",
          "phone": "+5511999990000",
          "missed": false,
          "answered": true,
          "answered_in": "browser",
          "via": "api",
          "user_id": null,
          "user_name": null,
          "actor_label": "Ana (Gonzaga)",
          "ended_by_label": null,
          "state": "completed",
          "ended_by": "contact",
          "requested_at": "2026-11-03T14:01:49Z",
          "started_at": "2026-11-03T14:01:50Z",
          "answered_at": "2026-11-03T14:01:58Z",
          "audio_connected_at": "2026-11-03T14:01:59Z",
          "ended_at": "2026-11-03T14:05:02Z",
          "duration_ms": 192000,
          "wait_duration_ms": 8000,
          "talk_duration_ms": 184000,
          "reason": "peer_hangup",
          "media_session_id": "6a1f0c52-8d3e-4b7a-9f21-3c5d7e9a0b14",
          "lead_id": null,
          "recording_state": "ready",
          "recording": null
        }
      },
      "CallMedia": {
        "type": "object",
        "description": "Onde conectar o áudio da ligação (WebSocket do hub de áudio). Veja o contrato em `POST …/calls`.",
        "required": [
          "url",
          "ticket",
          "expires_at"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "`wss://<host>/v1/calls/media?ticket=…`, já com o bilhete."
          },
          "ticket": {
            "type": "string",
            "description": "Bilhete assinado de uso único; vale 60 s para conectar (a ligação pode durar mais)."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Até quando o bilhete serve para conectar."
          }
        },
        "additionalProperties": false
      },
      "CallMediaStarted": {
        "type": "object",
        "description": "Resposta 202 de uma ação de ligação com áudio: a operação na fila e a sessão de áudio.",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "operation_id",
              "state",
              "media_session_id",
              "media"
            ],
            "properties": {
              "operation_id": {
                "type": "string",
                "format": "uuid"
              },
              "state": {
                "type": "string",
                "enum": [
                  "queued",
                  "running",
                  "succeeded"
                ]
              },
              "media_session_id": {
                "type": "string",
                "format": "uuid",
                "description": "A sessão de áudio (igual ao `operation_id`); aparece nos eventos `call.*`."
              },
              "media": {
                "$ref": "#/components/schemas/CallMedia"
              }
            }
          }
        },
        "additionalProperties": false
      },
      "CallRecording": {
        "type": "object",
        "required": [
          "id",
          "state",
          "duration_ms",
          "bytes",
          "notice_played",
          "notice_mode",
          "ready_at",
          "retention_until",
          "deleted_at",
          "failure_reason",
          "mime",
          "channels",
          "sample_rate_hz",
          "created_at",
          "deleted_reason"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "recording",
              "processing",
              "ready",
              "failed",
              "deleted"
            ],
            "description": "`recording` durante a ligação; `processing` sendo convertida (segundos); `ready` disponível em `GET …/calls/{callId}/recording`; `failed` sem arquivo (a pessoa desligou antes do fim do aviso, sem áudio, ou a conversão falhou); `deleted` apagada (por prazo ou por alguém)."
          },
          "duration_ms": {
            "type": [
              "integer",
              "null"
            ]
          },
          "bytes": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Tamanho do arquivo Ogg/Opus."
          },
          "notice_played": {
            "type": "boolean",
            "description": "O aviso de gravação tocou inteiro no início. `false`: a pessoa desligou durante o aviso (gravação descartada, `state: failed`) ou a ligação foi gravada sem aviso por escolha (veja `notice_mode`)."
          },
          "notice_mode": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "played",
              "skipped_by_choice",
              "incomplete",
              null
            ],
            "description": "Como foi o aviso: `played` (tocou inteiro), `skipped_by_choice` (a ligação ou o padrão do número dispensou o aviso; a gravação fica guardada — quem escolheu é a pessoa da ligação, `user_id`, ou a chave da API, `via: api`) ou `incomplete` (a pessoa desligou durante um aviso que devia tocar; gravação descartada). `null` enquanto grava."
          },
          "ready_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "retention_until": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Quando a gravação é apagada automaticamente: o prazo do número a partir de quando ficou pronta (7 dias sem o módulo Gravações no FlowZap)."
          },
          "deleted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "failure_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Com `state: failed`, o motivo: `notice_incomplete` (a pessoa desligou durante o aviso), `no_audio` (o áudio nunca chegou), `key_mismatch`, `not_closed` (a ligação não fechou a gravação em 3 horas), `not_processed` (a conversão não terminou em 6 horas), `transcode_failed` ou outro código estável. `null` nos demais estados. Toda gravação que falha gera o webhook `call.recording_failed`."
          },
          "mime": {
            "type": "string",
            "enum": [
              "audio/ogg; codecs=opus"
            ],
            "description": "Formato do arquivo (o mesmo `Content-Type` de `GET …/recording`, sem os parâmetros)."
          },
          "channels": {
            "type": "integer",
            "enum": [
              2
            ],
            "description": "Estéreo: canal esquerdo, a outra pessoa; canal direito, o que ela ouviu (o aviso e a equipe)."
          },
          "sample_rate_hz": {
            "type": "integer",
            "enum": [
              16000
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Quando a gravação começou (UTC)."
          },
          "deleted_reason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "retention",
              "module_removed",
              "user",
              "api",
              null
            ],
            "description": "Com `state: deleted`, por que foi apagada: `retention` (fim do prazo do número), `module_removed` (o número perdeu o módulo Gravações no FlowZap, o prazo caiu para 7 dias e acabou), `user` (uma pessoa da equipe, pelo console) ou `api` (uma chave, `DELETE …/recording`). `null` nos demais estados."
          }
        },
        "additionalProperties": false,
        "example": {
          "id": "8c0e9a52-3b1f-4d7e-a1c2-5e6f7a8b9c0d",
          "state": "ready",
          "duration_ms": 184000,
          "bytes": 552310,
          "notice_played": true,
          "notice_mode": "played",
          "ready_at": "2026-11-03T14:05:12Z",
          "retention_until": "2026-11-10T14:05:12Z",
          "deleted_at": null,
          "failure_reason": null,
          "mime": "audio/ogg; codecs=opus",
          "channels": 2,
          "sample_rate_hz": 16000,
          "created_at": "2026-11-03T14:01:58Z",
          "deleted_reason": null
        }
      },
      "CallRecordingPolicy": {
        "type": "object",
        "required": [
          "instance_id",
          "enabled",
          "retention_days",
          "module_active",
          "notice_text",
          "notice_default",
          "quota",
          "updated_at"
        ],
        "properties": {
          "instance_id": {
            "type": "string",
            "format": "uuid"
          },
          "enabled": {
            "type": "boolean"
          },
          "retention_days": {
            "type": "integer",
            "description": "Dias que uma gravação nova fica guardada: 7 sem o módulo; 7 a 90 com o módulo Gravações no FlowZap."
          },
          "module_active": {
            "type": "boolean",
            "description": "O número tem o módulo pago Gravações no FlowZap (ouvir e baixar no console, guardar até 90 dias)."
          },
          "notice_text": {
            "type": "string",
            "description": "O aviso falado no início de cada ligação gravada."
          },
          "notice_default": {
            "type": "boolean",
            "description": "`true` (padrão): toda ligação gravada começa com o aviso, a não ser que a ligação peça para não tocar (`recording_notice: false`). `false`: só toca quando a ligação pede (`recording_notice: true`)."
          },
          "quota": {
            "type": "object",
            "required": [
              "used_bytes",
              "limit_bytes"
            ],
            "properties": {
              "used_bytes": {
                "type": "integer"
              },
              "limit_bytes": {
                "type": "integer"
              }
            },
            "additionalProperties": false
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "CallRecordingPolicyInput": {
        "type": "object",
        "required": [
          "enabled"
        ],
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "retention_days": {
            "type": "integer",
            "minimum": 7,
            "maximum": 90,
            "description": "Acima de 7 só com o módulo Gravações no FlowZap (senão 403 `recording_module_required`)."
          },
          "notice_default": {
            "type": "boolean",
            "description": "Tocar o aviso de gravação por padrão. Ausente: fica como está. Sem o aviso, a empresa precisa informar a gravação ao cliente de outra forma (LGPD)."
          }
        },
        "additionalProperties": false
      },
      "CallsAddon": {
        "type": "object",
        "description": "Ligações pelo WhatsApp (R$ 39 por número/mês): quantidade contratada, a que vale agora (assinatura, licença ou cortesia), o máximo do plano, o preço por número, a redução agendada e o aumento ainda por pagar (com o link).",
        "properties": {
          "call_quantity": {
            "type": "integer"
          },
          "call_quantity_in_force": {
            "type": "integer"
          },
          "max_quantity": {
            "type": [
              "integer",
              "null"
            ]
          },
          "call_unit_amount_minor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Centavos."
          },
          "scheduled_change": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "to_quantity": {
                "type": "integer"
              },
              "effective_at": {
                "type": "string",
                "format": "date-time"
              },
              "renewal_prepared": {
                "type": "boolean"
              }
            }
          },
          "pending_increase": {
            "type": [
              "object",
              "null"
            ],
            "description": "Aumento aguardando pagamento: `change_id`, `to_quantity`, `amount_minor`, `method`, `link`, `attempt_state`…"
          }
        }
      },
      "Campaign": {
        "type": "object",
        "required": [
          "id",
          "name",
          "message_type",
          "state",
          "pause_reason",
          "scheduled_at",
          "next_send_at",
          "delay_ms",
          "respect_business_hours",
          "window",
          "daily_limit",
          "variant_count",
          "total_recipients",
          "skipped_unconsented",
          "created_at",
          "started_at",
          "finished_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "message_type": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "scheduled",
              "running",
              "paused",
              "paused_disconnected",
              "paused_by_safety",
              "completed",
              "canceled"
            ],
            "description": "`paused_by_safety`: pausa automática (motivo em `pause_reason`); retome com `/resume`."
          },
          "pause_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "`manual`, `number_not_connected`, `send_unavailable`, `failure_rate` (mais de 20% de falhas nos últimos 50 envios) ou `reachout_timelock` (o WhatsApp limitou conversas novas do número)."
          },
          "scheduled_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "next_send_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "delay_ms": {
            "type": "object",
            "required": [
              "min",
              "max"
            ],
            "properties": {
              "min": {
                "type": "integer"
              },
              "max": {
                "type": "integer"
              }
            },
            "additionalProperties": false
          },
          "respect_business_hours": {
            "type": "boolean"
          },
          "window": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/CampaignWindow"
              },
              {
                "type": "null"
              }
            ],
            "description": "Janela de envio em vigor (com `respect_business_hours`, a de seg–sáb 8h–20h)."
          },
          "daily_limit": {
            "type": "integer"
          },
          "variant_count": {
            "type": "integer",
            "description": "Número de variações de texto; 0 quando todos recebem o modelo."
          },
          "total_recipients": {
            "type": "integer",
            "minimum": 0
          },
          "skipped_unconsented": {
            "type": "integer",
            "minimum": 0
          },
          "counts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            }
          },
          "message_states": {
            "type": "object",
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            }
          },
          "created_at": {
            "type": "string"
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": false
      },
      "CampaignMetrics": {
        "type": "object",
        "required": [
          "sent",
          "delivered",
          "read",
          "failed",
          "replies",
          "opt_outs"
        ],
        "properties": {
          "sent": {
            "type": "integer",
            "description": "Envios aceitos."
          },
          "delivered": {
            "type": "integer"
          },
          "read": {
            "type": "integer"
          },
          "failed": {
            "type": "integer",
            "description": "Recusados ao enviar, ou mensagens que falharam/expiraram."
          },
          "replies": {
            "type": "integer",
            "description": "Destinatários que responderam depois do envio (primeira mensagem de cada um)."
          },
          "opt_outs": {
            "type": "integer",
            "description": "Leads que pediram para sair depois de receber."
          }
        }
      },
      "CampaignRecipient": {
        "type": "object",
        "required": [
          "id",
          "position",
          "phone",
          "state",
          "error_code",
          "message_id",
          "message_state",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "position": {
            "type": "integer"
          },
          "phone": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "pending",
              "accepted",
              "skipped",
              "failed",
              "canceled"
            ]
          },
          "error_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "message_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "message_state": {
            "type": [
              "string",
              "null"
            ]
          },
          "updated_at": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "CampaignReport": {
        "type": "object",
        "required": [
          "campaign_id",
          "bucket",
          "time_zone",
          "totals",
          "series",
          "replies_truncated"
        ],
        "properties": {
          "campaign_id": {
            "type": "string",
            "format": "uuid"
          },
          "bucket": {
            "type": "string",
            "enum": [
              "hour",
              "day"
            ]
          },
          "time_zone": {
            "type": "string"
          },
          "totals": {
            "$ref": "#/components/schemas/CampaignMetrics"
          },
          "series": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CampaignSeriesPoint"
            }
          },
          "replies_truncated": {
            "type": "boolean",
            "description": "As respostas foram contadas sobre uma janela limitada (5000 envios e 5000 mensagens recebidas)."
          }
        }
      },
      "CampaignSeriesPoint": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CampaignMetrics"
          },
          {
            "type": "object",
            "required": [
              "at"
            ],
            "properties": {
              "at": {
                "type": "string",
                "format": "date-time",
                "description": "Início da hora/dia (America/Sao_Paulo), em ISO 8601."
              }
            }
          }
        ]
      },
      "CampaignSummary": {
        "type": "object",
        "required": [
          "time_zone",
          "today",
          "campaigns",
          "period",
          "series",
          "paused_by_safety",
          "replies_truncated"
        ],
        "properties": {
          "time_zone": {
            "type": "string"
          },
          "today": {
            "type": "object",
            "required": [
              "date",
              "sent",
              "daily_limit",
              "remaining"
            ],
            "properties": {
              "date": {
                "type": "string",
                "format": "date"
              },
              "sent": {
                "type": "integer"
              },
              "daily_limit": {
                "type": "integer",
                "description": "O menor `daily_limit` entre as campanhas ativas (200 sem campanha ativa)."
              },
              "remaining": {
                "type": "integer"
              }
            }
          },
          "campaigns": {
            "type": "object",
            "description": "Campanhas do número por estado.",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "period": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CampaignMetrics"
              },
              {
                "type": "object",
                "required": [
                  "days",
                  "since"
                ],
                "properties": {
                  "days": {
                    "type": "integer"
                  },
                  "since": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            ]
          },
          "series": {
            "type": "array",
            "description": "Por dia, dos envios feitos no período.",
            "items": {
              "$ref": "#/components/schemas/CampaignSeriesPoint"
            }
          },
          "paused_by_safety": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "name",
                "pause_reason"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string"
                },
                "pause_reason": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          },
          "replies_truncated": {
            "type": "boolean"
          }
        }
      },
      "CampaignWindow": {
        "type": "object",
        "required": [
          "days",
          "start",
          "end"
        ],
        "properties": {
          "days": {
            "type": "array",
            "minItems": 1,
            "maxItems": 7,
            "uniqueItems": true,
            "items": {
              "type": "integer",
              "minimum": 1,
              "maximum": 7
            },
            "description": "Dias da semana ISO (1 = segunda … 7 = domingo)."
          },
          "start": {
            "type": "string",
            "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
            "description": "Início (HH:MM, incluso)."
          },
          "end": {
            "type": "string",
            "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
            "description": "Fim (HH:MM, exclusivo), depois do início."
          },
          "tz": {
            "type": "string",
            "default": "America/Sao_Paulo",
            "description": "Fuso IANA."
          }
        },
        "additionalProperties": false
      },
      "ChatHistoryMessage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ChatHistoryMessageBase"
          },
          {
            "$ref": "#/components/schemas/ChatHistoryMessageExtras"
          }
        ]
      },
      "ChatHistoryMessageBase": {
        "type": "object",
        "required": [
          "id",
          "chat_jid",
          "direction",
          "from_me",
          "sender_jid",
          "sender_name",
          "source",
          "kind",
          "text",
          "timestamp",
          "state",
          "command_id"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "chat_jid": {
            "type": "string"
          },
          "direction": {
            "type": "string",
            "enum": [
              "in",
              "out"
            ]
          },
          "from_me": {
            "type": "boolean"
          },
          "sender_jid": {
            "type": [
              "string",
              "null"
            ]
          },
          "sender_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "api",
              "console",
              "phone",
              "contact"
            ]
          },
          "kind": {
            "type": "string"
          },
          "text": {
            "type": [
              "string",
              "null"
            ]
          },
          "timestamp": {
            "type": "string"
          },
          "state": {
            "type": [
              "string",
              "null"
            ]
          },
          "command_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "revoked": {
            "$ref": "#/components/schemas/MessageRevoked"
          },
          "edits": {
            "type": "array",
            "description": "Versões posteriores da mensagem, da mais antiga à mais nova; a última é o texto atual. `text` continua sendo o original.",
            "items": {
              "$ref": "#/components/schemas/MessageEdit"
            }
          },
          "applied": {
            "type": "boolean",
            "description": "Só numa edição ou exclusão (`kind` edit/revoke) cuja mensagem alvo está na leitura: true se marcou o alvo; false se foi ignorada (não veio de quem enviou o alvo, nem de um administrador do grupo apontando para ele, ou chegou fora do prazo do WhatsApp)."
          }
        }
      },
      "ChatHistoryMessageExtras": {
        "type": "object",
        "description": "Campos a mais de um item de `GET …/chats/{jid}/messages` (além de `ChatHistoryMessage`). `source` passa a ter também `console` (enviado por uma pessoa no console). Os campos de contexto e formato da mídia (`quoted_participant`, `mentions`, `forwarded`, `forwarding_score`, `ptt`, `width`, `height`, `duration_seconds`, `has_thumbnail`) só existem nas mensagens recebidas guardadas a partir desta versão do motor.",
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "api",
              "console",
              "phone",
              "contact"
            ]
          },
          "inbox_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Recebidas: o ID de `GET …/inbound/{id}` e `GET …/inbound/{inboxId}/media`; `null` nos envios do número."
          },
          "actor_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Envios: o atendente (pessoa do console ou `actor_label` da API)."
          },
          "caption": {
            "type": [
              "string",
              "null"
            ]
          },
          "media": {
            "$ref": "#/components/schemas/HistoryMedia"
          },
          "quoted_message_id": {
            "type": "string",
            "description": "ID no WhatsApp da mensagem citada."
          },
          "quoted_participant": {
            "type": "string",
            "description": "Quem escreveu a mensagem citada (JID), quando o WhatsApp informa."
          },
          "mentions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Pessoas mencionadas, como JID (telefone ou LID)."
          },
          "forwarded": {
            "type": "boolean"
          },
          "forwarding_score": {
            "type": "integer",
            "description": "Quantas vezes a mensagem já foi encaminhada."
          },
          "ptt": {
            "type": "boolean",
            "description": "Áudio gravado como mensagem de voz."
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "duration_seconds": {
            "type": "integer"
          },
          "has_thumbnail": {
            "type": "boolean"
          },
          "view_once": {
            "type": "boolean"
          }
        }
      },
      "ChatJid": {
        "type": "string",
        "pattern": "^(\\d{5,20}@(s\\.whatsapp\\.net|lid)|\\d{5,25}(-\\d{5,15})?@g\\.us)$",
        "description": "Conversa privada (pessoa) ou grupo."
      },
      "ChatSummary": {
        "type": "object",
        "required": [
          "jid",
          "alt_jid",
          "is_group",
          "name",
          "last_message",
          "inbound_count",
          "outbound_count",
          "unread_count",
          "last_activity_at",
          "archived",
          "pinned",
          "muted",
          "muted_until",
          "labels"
        ],
        "properties": {
          "jid": {
            "type": "string",
            "description": "JID da conversa como o WhatsApp a guarda: LID (`…@lid`) quando o provedor provou o par, senão o telefone (`…@s.whatsapp.net`) ou o grupo (`…@g.us`)."
          },
          "alt_jid": {
            "type": [
              "string",
              "null"
            ],
            "description": "A outra grafia da mesma conversa (telefone de um LID), quando provada; `null` se não conhecida."
          },
          "is_group": {
            "type": "boolean",
            "description": "`true` para conversa de grupo (`jid` termina em `@g.us`)."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Nome de perfil (`push_name`) que a pessoa usa no WhatsApp, da mensagem recebida mais recente da janela que o trouxe; não é o nome da agenda do celular nem o nome dado no CRM (use `GET …/contacts` e `GET …/crm/leads/{contact}`). `null` em grupos (veja `GET …/groups`) e quando a pessoa só recebeu mensagens."
          },
          "last_message": {
            "type": "object",
            "required": [
              "id",
              "direction",
              "kind",
              "text",
              "timestamp"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "direction": {
                "type": "string",
                "enum": [
                  "in",
                  "out"
                ]
              },
              "kind": {
                "type": "string"
              },
              "text": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "timestamp": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "inbound_count": {
            "type": "integer",
            "minimum": 0
          },
          "outbound_count": {
            "type": "integer",
            "minimum": 0
          },
          "unread_count": {
            "type": "integer",
            "minimum": 0,
            "description": "Mensagens recebidas depois da nossa última resposta nesta conversa (enviada pela API, pelo console ou pelo celular), dentro da janela. Não é o contador de não lidas do WhatsApp nem a marca de leitura por pessoa do console (\"Conversas não lidas\", própria de cada atendente e só no console); em grupos conta toda mensagem depois da nossa última."
          },
          "last_activity_at": {
            "type": "string"
          },
          "archived": {
            "type": "boolean",
            "description": "Arquivada no WhatsApp (pelo celular, inclusive antes da conexão, ou por `POST …/chats/{jid}/archive`)."
          },
          "pinned": {
            "type": "boolean",
            "description": "Fixada no WhatsApp."
          },
          "muted": {
            "type": "boolean",
            "description": "Silenciada agora (um silêncio com prazo vencido volta a `false`)."
          },
          "muted_until": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Com `muted`: quando o silêncio acaba; `null` silencia até reativar."
          },
          "labels": {
            "type": "array",
            "description": "Etiquetas da conversa (feitas no celular ou pela API), com nome e cor; uma etiqueta ainda não sincronizada não aparece aqui (veja `GET …/chats/{jid}/labels`).",
            "items": {
              "type": "object",
              "required": [
                "label_id",
                "name",
                "color"
              ],
              "properties": {
                "label_id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "color": {
                  "type": "integer"
                }
              },
              "additionalProperties": false
            }
          }
        },
        "additionalProperties": false
      },
      "ChatwootConfig": {
        "type": "object",
        "required": [
          "instance_id",
          "url",
          "account_id",
          "inbox_id",
          "api_access_token",
          "enabled",
          "sign_messages",
          "reopen_conversation",
          "ignore_groups",
          "webhook_url",
          "last_error_code",
          "last_error_at",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "instance_id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string"
          },
          "account_id": {
            "type": "integer",
            "minimum": 1
          },
          "inbox_id": {
            "type": "integer",
            "minimum": 1
          },
          "api_access_token": {
            "type": "string",
            "description": "Sempre mascarado: `****` e os últimos caracteres."
          },
          "enabled": {
            "type": "boolean"
          },
          "sign_messages": {
            "type": "boolean"
          },
          "reopen_conversation": {
            "type": "boolean"
          },
          "ignore_groups": {
            "type": "boolean"
          },
          "webhook_url": {
            "type": "string",
            "description": "Cole este endereço como webhook da caixa de entrada no Chatwoot."
          },
          "last_error_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_error_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "ChatwootConfigInput": {
        "type": "object",
        "required": [
          "url",
          "account_id",
          "inbox_id",
          "enabled"
        ],
        "properties": {
          "url": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2048,
            "description": "Endereço https do seu Chatwoot."
          },
          "account_id": {
            "type": "integer",
            "minimum": 1
          },
          "inbox_id": {
            "type": "integer",
            "minimum": 1
          },
          "api_access_token": {
            "type": "string",
            "minLength": 8,
            "maxLength": 256,
            "description": "Token de acesso. Pode ser omitido para manter o já salvo."
          },
          "enabled": {
            "type": "boolean"
          },
          "sign_messages": {
            "type": "boolean",
            "default": false
          },
          "reopen_conversation": {
            "type": "boolean",
            "default": true
          },
          "ignore_groups": {
            "type": "boolean",
            "default": true
          }
        },
        "additionalProperties": false
      },
      "ChatwootHookResult": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "status",
              "reason"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "ignored"
                ]
              },
              "reason": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": [
              "status",
              "messages"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "sent"
                ]
              },
              "messages": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "state",
                    "replayed"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "state": {
                      "type": "string"
                    },
                    "replayed": {
                      "type": "boolean"
                    }
                  },
                  "additionalProperties": false
                }
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "ConnectionEvent": {
        "type": "object",
        "description": "Último aviso de conexão que o WhatsApp deu para o número.",
        "required": [
          "state",
          "session_state",
          "reason",
          "ban_expires_at",
          "observed_at",
          "event_id"
        ],
        "properties": {
          "state": {
            "type": "string",
            "description": "`connected`, `disconnected`, `logged_out`, `temporary_ban`, `stream_replaced` ou `client_outdated`."
          },
          "session_state": {
            "type": [
              "string",
              "null"
            ],
            "description": "Situação da sessão para a qual o aviso leva (ex.: `needs_pairing`, `blocked`, `offline`)."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Motivo informado pelo WhatsApp em `logged_out` e `temporary_ban` (texto do WhatsApp, em inglês)."
          },
          "ban_expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "`temporary_ban`: quando o WhatsApp libera o número."
          },
          "observed_at": {
            "type": "string",
            "format": "date-time"
          },
          "event_id": {
            "type": "string",
            "format": "uuid",
            "description": "ID do evento (`GET /v1/events/{id}`)."
          }
        },
        "additionalProperties": false
      },
      "ContactCheckResult": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "phone",
                "exists",
                "jid",
                "lid",
                "verified_name"
              ],
              "properties": {
                "phone": {
                  "type": "string"
                },
                "exists": {
                  "type": "boolean",
                  "description": "O telefone tem WhatsApp."
                },
                "jid": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "lid": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "verified_name": {
                  "description": "Nome verificado de conta comercial, quando houver."
                }
              },
              "additionalProperties": false
            }
          }
        },
        "additionalProperties": false
      },
      "ControlEvent": {
        "type": "object",
        "description": "Evento de funil, atendimento ou gravação lido por `GET /v1/events/{id}` (pelo `event_id` do aviso). O `payload` é o recurso como está **agora** (não no momento do evento); recurso apagado depois vem `null`. Quem mudou e o motivo ficam no histórico do atendimento (`GET …/tickets/{id}/events`).",
        "required": [
          "id",
          "kind",
          "workspace_id",
          "instance_id",
          "observed_at",
          "created_at",
          "sequence",
          "payload"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "`event_id` do aviso."
          },
          "kind": {
            "type": "string",
            "enum": [
              "ticket.opened",
              "ticket.resolved",
              "ticket.reopened",
              "ticket.assigned",
              "ticket.pending_set",
              "ticket.pending_cleared",
              "lead.stage_changed",
              "csat.answered",
              "call.recording_ready",
              "call.recording_deleted",
              "call.recording_failed"
            ]
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "instance_id": {
            "type": "string",
            "format": "uuid"
          },
          "observed_at": {
            "type": "string",
            "format": "date-time",
            "description": "Quando o evento aconteceu (`occurred_at` do aviso)."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "sequence": {
            "type": "integer",
            "minimum": 1
          },
          "payload": {
            "type": "object",
            "required": [
              "resource_type",
              "resource_id"
            ],
            "properties": {
              "resource_type": {
                "type": "string",
                "enum": [
                  "ticket",
                  "lead",
                  "call"
                ],
                "description": "`ticket` para `ticket.*` e `csat.answered`; `lead` para `lead.stage_changed`; `call` para `call.recording_*`."
              },
              "resource_id": {
                "type": "string",
                "format": "uuid"
              },
              "ticket": {
                "description": "O atendimento, como em `GET …/tickets/{id}` (ou `null`).",
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Ticket"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "lead": {
                "description": "Estado do lead (ou `null`); o lead completo está em `GET …/crm/leads/{contato}`.",
                "oneOf": [
                  {
                    "type": "object",
                    "required": [
                      "id",
                      "stage_id",
                      "status",
                      "assigned_user_id",
                      "updated_at"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "stage_id": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "format": "uuid"
                      },
                      "status": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "assigned_user_id": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "format": "uuid"
                      },
                      "updated_at": {
                        "type": "string",
                        "format": "date-time"
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "call": {
                "description": "A ligação, como em `GET …/calls/{id}` (ou `null`).",
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Call"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "CreateAudienceInput": {
        "type": "object",
        "description": "Informe `group_jids` (grupos em que o número está) **ou** `all: true` (todos os grupos do número), nunca os dois.",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "group_jids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "type": "string",
              "pattern": "^\\d{5,40}(-\\d+)?@g\\.us$"
            }
          },
          "all": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "additionalProperties": false
      },
      "CreateCampaignInput": {
        "type": "object",
        "required": [
          "name",
          "message",
          "recipients"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "message": {
            "$ref": "#/components/schemas/MessageTemplate",
            "description": "Modelo da mensagem. O texto (`text.body`, `caption`, `buttons.text` ou `list.text`) aceita personalização: `{{nome}}`, `{{primeiro_nome}}` e `{{campo:<chave>}}` (campos do lead no CRM), com texto alternativo depois de `|` para quem não tem o dado: `{{primeiro_nome|cliente}}`. Sem dado e sem alternativo, fica vazio. Marcadores desconhecidos ou mal fechados: 422 `invalid_placeholder`. Com `variants`, o texto do modelo é substituído pela variação (e pode ser omitido)."
          },
          "variants": {
            "type": "array",
            "minItems": 2,
            "maxItems": 5,
            "description": "De 2 a 5 textos alternados por destinatário, em ordem (o 1º recebe a 1ª, o 2º a 2ª…). Mídia e demais campos são os do modelo. Só para mensagens com texto: text, image, video, document, buttons, list.",
            "items": {
              "type": "object",
              "required": [
                "text"
              ],
              "properties": {
                "text": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 4096
                }
              },
              "additionalProperties": false
            }
          },
          "recipients": {
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/E164"
                },
                "minItems": 1,
                "maxItems": 5000
              },
              {
                "type": "object",
                "required": [
                  "tag_id"
                ],
                "properties": {
                  "tag_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Etiqueta de lead do CRM."
                  }
                },
                "additionalProperties": false
              }
            ]
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data e hora ISO 8601 com fuso (ex.: `2026-10-01T18:00:00Z`)."
          },
          "delay_ms": {
            "type": "object",
            "required": [
              "min",
              "max"
            ],
            "properties": {
              "min": {
                "type": "integer",
                "minimum": 3000,
                "maximum": 600000
              },
              "max": {
                "type": "integer",
                "minimum": 3000,
                "maximum": 600000
              }
            },
            "additionalProperties": false,
            "description": "Pausa aleatória (uniforme) entre dois envios. Padrão 5000–15000. Alternativa: `delay_min_ms` + `delay_max_ms` (não envie os dois formatos).",
            "default": {
              "min": 5000,
              "max": 15000
            }
          },
          "delay_min_ms": {
            "type": "integer",
            "minimum": 3000,
            "maximum": 600000,
            "description": "Igual a `delay_ms.min`; exige `delay_max_ms`."
          },
          "delay_max_ms": {
            "type": "integer",
            "minimum": 3000,
            "maximum": 600000,
            "description": "Igual a `delay_ms.max`; exige `delay_min_ms`."
          },
          "respect_business_hours": {
            "type": "boolean",
            "description": "Envia só de segunda a sábado, das 8h às 20h (horário de Brasília). Equivale a `window: {days: [1,2,3,4,5,6], start: \"08:00\", end: \"20:00\"}`; não use junto com `window`.",
            "default": false
          },
          "window": {
            "$ref": "#/components/schemas/CampaignWindow"
          },
          "daily_limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000,
            "default": 200,
            "description": "Máximo de envios por dia do número (dia em America/Sao_Paulo), somando todas as campanhas dele. Atingido o limite, a campanha espera o dia seguinte."
          },
          "skip_unconsented": {
            "type": "boolean",
            "description": "Cria a campanha só com quem deu consentimento, em vez de responder 422.",
            "default": false
          }
        },
        "additionalProperties": false
      },
      "CreateGroupBroadcastInput": {
        "type": "object",
        "required": [
          "name",
          "groups",
          "message"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "groups": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/GroupJid"
            },
            "description": "Grupos em que o número é **administrador**, na ordem de envio. Grupos em que ele só participa: 422 `not_group_admin` (ou pulados com `skip_non_admin`)."
          },
          "message": {
            "$ref": "#/components/schemas/MessageTemplate",
            "description": "Corpo de envio sem `to` (texto, mídia por `media.id` ou URL https, localização, enquete…). Vai igual para todos os grupos, sem personalização."
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time",
            "description": "Início agendado (até 30 dias)."
          },
          "delay_min_ms": {
            "type": "integer",
            "minimum": 3000,
            "maximum": 600000,
            "description": "Pausa mínima entre dois grupos (padrão 10000). Junto com `delay_max_ms`."
          },
          "delay_max_ms": {
            "type": "integer",
            "minimum": 3000,
            "maximum": 600000,
            "description": "Pausa máxima entre dois grupos (padrão 30000)."
          },
          "daily_limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000,
            "description": "Mensagens por dia do número (dia de Brasília), somando os envios para grupos do número. Padrão 200."
          },
          "window": {
            "$ref": "#/components/schemas/CampaignWindow"
          },
          "skip_non_admin": {
            "type": "boolean",
            "default": false,
            "description": "true: cria só com os grupos administrados, em vez de responder 422."
          }
        },
        "additionalProperties": false
      },
      "CreateGroupInput": {
        "type": "object",
        "required": [
          "name",
          "participants"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "participants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/E164"
            },
            "minItems": 1,
            "maxItems": 256
          }
        },
        "additionalProperties": false
      },
      "CreateInstanceInput": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40
            },
            "maxItems": 10,
            "default": []
          }
        },
        "additionalProperties": false
      },
      "CreateLaunchLinkInput": {
        "type": "object",
        "required": [
          "slug",
          "name",
          "groups"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{1,46}[a-z0-9]$",
            "description": "Final do endereço público `/g/<slug>`. Único para sempre: nem um link apagado libera o slug."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "groups": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/GroupJid"
            },
            "description": "Grupos administrados pelo número, na ordem em que enchem."
          },
          "cap": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1024,
            "default": 1024,
            "description": "Pessoas por grupo antes de passar para o próximo."
          },
          "auto_create": {
            "$ref": "#/components/schemas/AutoCreateInput"
          }
        },
        "additionalProperties": false
      },
      "CrmField": {
        "type": "object",
        "required": [
          "id",
          "key",
          "label",
          "type",
          "options",
          "position",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "key": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "text",
              "number",
              "date",
              "select",
              "phone",
              "email"
            ]
          },
          "options": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "position": {
            "type": "integer"
          },
          "created_at": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "CrmFieldInput": {
        "type": "object",
        "required": [
          "key",
          "label",
          "type"
        ],
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_.-]{1,40}$",
            "description": "Chave do valor em `fields` do lead."
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "type": {
            "type": "string",
            "enum": [
              "text",
              "number",
              "date",
              "select",
              "phone",
              "email"
            ],
            "description": "`date` é `AAAA-MM-DD`; `number` aceita vírgula ou ponto decimal."
          },
          "options": {
            "type": "array",
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40
            },
            "description": "Só (e obrigatório) para `select`."
          }
        },
        "additionalProperties": false
      },
      "CrmFieldPatch": {
        "type": "object",
        "description": "Campos omitidos ficam como estão. A chave não muda.",
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "type": {
            "type": "string",
            "enum": [
              "text",
              "number",
              "date",
              "select",
              "phone",
              "email"
            ]
          },
          "options": {
            "type": "array",
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40
            }
          },
          "position": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          }
        },
        "additionalProperties": false
      },
      "CrmLead": {
        "type": "object",
        "required": [
          "id",
          "contact",
          "name",
          "status",
          "assigned_user_id",
          "tags",
          "stage_id",
          "last_activity_at",
          "fields",
          "opted_in",
          "opted_out_at",
          "consented",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "contact": {
            "type": "string"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "assigned_user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "stage_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Etapa do funil (`GET …/crm/stages`); `null`: sem etapa. Muda com `POST …/crm/leads/{contact}/move`."
          },
          "last_activity_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "Última mensagem recebida do contato."
          },
          "fields": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Valores dos campos personalizados (`GET …/crm/fields`), conferidos pelo tipo do campo ao gravar."
          },
          "opted_in": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "at",
              "source"
            ],
            "properties": {
              "at": {
                "type": "string"
              },
              "source": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "opted_out_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "consented": {
            "type": "boolean",
            "description": "Tem consentimento e não saiu da lista."
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "CrmLeadInput": {
        "type": "object",
        "description": "Campos omitidos ficam como estão.",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 120
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 40
          },
          "assigned_user_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "maxItems": 20,
            "uniqueItems": true
          },
          "fields": {
            "type": "object",
            "maxProperties": 20,
            "propertyNames": {
              "pattern": "^[A-Za-z0-9_.-]{1,40}$"
            },
            "additionalProperties": {
              "type": "string",
              "maxLength": 500
            }
          },
          "opted_in": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "at",
              "source"
            ],
            "properties": {
              "at": {
                "type": "string",
                "format": "date-time",
                "description": "Data e hora ISO 8601 com fuso (ex.: `2026-10-01T18:00:00Z`)."
              },
              "source": {
                "type": "string",
                "minLength": 1,
                "maxLength": 80
              }
            },
            "additionalProperties": false
          },
          "opted_out_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Data e hora ISO 8601 com fuso (ex.: `2026-10-01T18:00:00Z`)."
          }
        },
        "additionalProperties": false
      },
      "CrmMoveInput": {
        "type": "object",
        "required": [
          "stage_id"
        ],
        "properties": {
          "stage_id": {
            "type": "string",
            "format": "uuid"
          },
          "before_id": {
            "type": "string",
            "format": "uuid",
            "description": "Fica antes deste contato da coluna."
          },
          "after_id": {
            "type": "string",
            "format": "uuid",
            "description": "Fica depois deste contato da coluna. Sem `before_id`/`after_id`, vai para o topo."
          }
        },
        "additionalProperties": false
      },
      "CrmNote": {
        "type": "object",
        "required": [
          "id",
          "lead_id",
          "text",
          "author",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "lead_id": {
            "type": "string",
            "format": "uuid"
          },
          "text": {
            "type": "string"
          },
          "author": {
            "type": "object",
            "required": [
              "kind",
              "ref"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "api_key",
                  "user"
                ]
              },
              "ref": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "created_at": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "CrmNoteInput": {
        "type": "object",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "author_user_id": {
            "type": "string",
            "format": "uuid",
            "description": "Membro da organização; sem ele, a autora é a chave de API. Só a pessoa que criou a chave, ou qualquer pessoa da equipe quando quem a criou é dono ou administrador (senão 403 `author_not_allowed`)."
          }
        },
        "additionalProperties": false
      },
      "CrmPipeline": {
        "type": "object",
        "required": [
          "columns"
        ],
        "properties": {
          "columns": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CrmPipelineColumn"
            }
          }
        },
        "additionalProperties": false
      },
      "CrmPipelineCard": {
        "type": "object",
        "required": [
          "id",
          "contact",
          "name",
          "stage_id",
          "tags",
          "assigned_user_id",
          "last_activity_at",
          "open_ticket",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "ID do lead (use em `before_id`/`after_id` ao mover)."
          },
          "contact": {
            "type": "string",
            "description": "Telefone `+55…` ou contato `…@lid`."
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "stage_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "assigned_user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_activity_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "open_ticket": {
            "type": "boolean",
            "description": "O contato tem atendimento aberto."
          },
          "created_at": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "CrmPipelineColumn": {
        "type": "object",
        "required": [
          "stage",
          "total",
          "contacts",
          "next_cursor"
        ],
        "properties": {
          "stage": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/CrmStage"
              },
              {
                "type": "null"
              }
            ],
            "description": "`null`: contatos sem etapa."
          },
          "total": {
            "type": "integer",
            "description": "Contatos da coluna com os filtros pedidos."
          },
          "contacts": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/CrmPipelineCard"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Próxima página desta coluna: repita com `stage` e `cursor`."
          }
        },
        "additionalProperties": false
      },
      "CrmStage": {
        "type": "object",
        "required": [
          "id",
          "name",
          "color",
          "kind",
          "position",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "color": {
            "type": "integer"
          },
          "kind": {
            "type": "string",
            "enum": [
              "open",
              "won",
              "lost"
            ]
          },
          "position": {
            "type": "integer"
          },
          "created_at": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "CrmStageInput": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "color": {
            "type": "integer",
            "minimum": 0,
            "maximum": 19,
            "default": 0,
            "description": "Mesma paleta das etiquetas de lead."
          },
          "kind": {
            "type": "string",
            "enum": [
              "open",
              "won",
              "lost"
            ],
            "default": "open",
            "description": "`won` (ganho) e `lost` (perdido) marcam as etapas de fechamento."
          }
        },
        "additionalProperties": false
      },
      "CrmStagePatch": {
        "type": "object",
        "description": "Campos omitidos ficam como estão.",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "color": {
            "type": "integer",
            "minimum": 0,
            "maximum": 19
          },
          "kind": {
            "type": "string",
            "enum": [
              "open",
              "won",
              "lost"
            ]
          },
          "position": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1200,
            "description": "Nova posição da coluna (0 = primeira); as outras se ajustam."
          }
        },
        "additionalProperties": false
      },
      "CrmTag": {
        "type": "object",
        "required": [
          "id",
          "name",
          "color",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "color": {
            "type": "integer"
          },
          "created_at": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "CrmTagInput": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "color": {
            "type": "integer",
            "minimum": 0,
            "maximum": 19,
            "default": 0
          }
        },
        "additionalProperties": false
      },
      "CsatSummary": {
        "type": "object",
        "required": [
          "days",
          "answered",
          "average",
          "distribution",
          "response_rate"
        ],
        "properties": {
          "days": {
            "type": "integer"
          },
          "answered": {
            "type": "integer"
          },
          "average": {
            "type": [
              "number",
              "null"
            ],
            "description": "Média de 1 a 5; `null` sem respostas."
          },
          "distribution": {
            "type": "array",
            "minItems": 5,
            "maxItems": 5,
            "items": {
              "type": "integer"
            },
            "description": "Quantas respostas com nota 1, 2, 3, 4 e 5."
          },
          "response_rate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Respondidas ÷ enviadas no período (0 a 1); `null` se nenhuma foi enviada."
          }
        },
        "additionalProperties": false
      },
      "E164": {
        "type": "string",
        "pattern": "^\\+[1-9]\\d{6,14}$",
        "description": "Telefone no formato E.164, com `+` e DDI (ex.: `+5511912345678`)."
      },
      "EngineEvent": {
        "type": "object",
        "required": [
          "id",
          "kind",
          "workspace_id",
          "instance_id",
          "observed_at",
          "created_at",
          "payload"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "instance.connection",
              "instance.reachout_timelock",
              "presence.update",
              "chat.presence",
              "group.update",
              "group.joined",
              "contact.picture",
              "contact.update",
              "contact.blocklist",
              "call.offer",
              "call.accept",
              "call.terminate",
              "call.reject",
              "call.started",
              "call.ringing",
              "call.answered",
              "call.media_connected",
              "call.ended",
              "label.edit",
              "label.chat",
              "label.message",
              "chat.update",
              "history.sync",
              "newsletter.join",
              "newsletter.leave",
              "newsletter.mute_change",
              "newsletter.live_update"
            ]
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "instance_id": {
            "type": "string",
            "format": "uuid"
          },
          "observed_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "payload": {
            "type": "object",
            "additionalProperties": true,
            "description": "Conteúdo do evento, decifrado nesta leitura."
          }
        },
        "additionalProperties": false
      },
      "EngineResult": {
        "type": "object",
        "additionalProperties": true,
        "description": "Resultado devolvido pelo motor do WhatsApp para esta operação (objeto JSON com chaves em snake_case)."
      },
      "Error": {
        "type": "object",
        "description": "Envelope único de erro de todas as rotas.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "description": "Alguns erros trazem campos extras (ex.: `rejected` e `total` em `consent_required`).",
            "required": [
              "code",
              "message",
              "request_id",
              "retryable"
            ],
            "properties": {
              "code": {
                "$ref": "#/components/schemas/ErrorCode"
              },
              "message": {
                "type": "string",
                "description": "Hoje repete o código; não dependa do texto."
              },
              "request_id": {
                "type": "string",
                "description": "Mesmo valor do cabeçalho `X-Request-Id` desta resposta (UUID gerado, ou o valor enviado pelo cliente); fica no log de erros, informe-o ao suporte."
              },
              "retryable": {
                "type": "boolean",
                "description": "true quando repetir depois pode dar certo: 429 (exceto cotas do plano, sempre com `Retry-After`), 503 e 504. false em 4xx, 501 e no 502 de resultado incerto (confira antes de repetir)."
              }
            }
          }
        },
        "additionalProperties": false
      },
      "ErrorCode": {
        "type": "string",
        "description": "Códigos de erro estáveis da API (`error.code`) e motivos de falha de envio (`error_code`). A lista pode crescer: trate códigos desconhecidos pelo status HTTP e por `retryable`. Significado, se vale repetir e o que fazer: docs/api/erros.md.",
        "examples": [
          "idempotency_conflict"
        ],
        "x-extensible-enum": [
          "account_exists",
          "addon_change_refused",
          "after_sequence_requires_instance",
          "already_member",
          "already_sent",
          "api_access_token_required",
          "api_key_active",
          "api_key_not_active",
          "audience_empty",
          "audience_not_ready",
          "audio_conversion_unavailable",
          "audio_unreadable",
          "author_not_allowed",
          "bad_request",
          "before_or_after",
          "billing_read_unavailable",
          "billing_role_required",
          "billing_unavailable",
          "call_already_answering",
          "call_ended",
          "call_not_ringing",
          "call_quantity_exceeded",
          "call_target_not_allowed",
          "call_test_numbers_limit",
          "call_trial_not_enabled",
          "calls_not_enabled",
          "capacity_unavailable",
          "card_checkout_unavailable",
          "carousel_media_mixed",
          "carousel_media_too_large",
          "chatwoot_url_invalid",
          "checkout_expired",
          "checkout_offer_unavailable",
          "checkout_rejected",
          "checkout_unavailable",
          "collection_failed",
          "collection_in_progress",
          "collection_too_soon",
          "consent_required",
          "contact_already_linked",
          "contact_link_not_found",
          "conversation_not_found",
          "cursor_map_too_large",
          "cursor_needs_stage",
          "declaration_required",
          "delivery_in_progress",
          "disconnect_first",
          "download_failed",
          "draft_limit_reached",
          "empty_media",
          "endpoint_disabled",
          "endpoint_exists",
          "endpoint_limit_reached",
          "engine_capability_missing",
          "engine_error",
          "engine_not_connected",
          "engine_timeout",
          "engine_unavailable",
          "existing_account",
          "field_exists",
          "forbidden",
          "forward_media_expired",
          "forward_media_too_large",
          "forward_media_unavailable",
          "forward_not_allowed",
          "forward_not_supported",
          "from_me_required",
          "group_announce_only",
          "group_info_unavailable",
          "group_not_found",
          "groups_not_ready",
          "groups_unavailable",
          "history_import_off",
          "idempotency_conflict",
          "idempotency_key_mismatch",
          "idempotency_key_required",
          "image_too_large",
          "instance_not_in_workspace",
          "instance_requires_workspace",
          "invalid_action",
          "invalid_auto_replies",
          "invalid_before",
          "invalid_body",
          "invalid_broadcast_state",
          "invalid_call_id",
          "invalid_campaign_state",
          "invalid_caption",
          "invalid_color",
          "invalid_count",
          "invalid_cursor",
          "invalid_description",
          "invalid_duration",
          "invalid_ephemeral_timer",
          "invalid_expiration",
          "invalid_expiry",
          "invalid_field_value",
          "invalid_file_name",
          "invalid_group_jid",
          "invalid_group_name",
          "invalid_groups",
          "invalid_idempotency_key",
          "invalid_image",
          "invalid_input",
          "invalid_instance_state",
          "invalid_invite",
          "invalid_invite_code",
          "invalid_jid",
          "invalid_json",
          "invalid_label_id",
          "invalid_last_event_id",
          "invalid_media_kind",
          "invalid_media_url",
          "invalid_member_add_mode",
          "invalid_message",
          "invalid_message_id",
          "invalid_message_ids",
          "invalid_name",
          "invalid_newsletter_jid",
          "invalid_newsletter_name",
          "invalid_or_expired_invitation",
          "invalid_origin",
          "invalid_participant",
          "invalid_participants",
          "invalid_payload",
          "invalid_phone",
          "invalid_placeholder",
          "invalid_privacy_value",
          "invalid_proxy_url",
          "invalid_reaction",
          "invalid_schedule",
          "invalid_sender_result",
          "invalid_server_id",
          "invalid_server_ids",
          "invalid_since",
          "invalid_status_style",
          "invalid_text",
          "invalid_timer",
          "invalid_timestamp",
          "invalid_token",
          "invitation_closed",
          "invitation_email_mismatch",
          "invitation_idempotency_conflict",
          "invitation_not_found",
          "invitation_recipient_mismatch",
          "invite_expired",
          "invite_not_allowed",
          "invite_not_requested",
          "invite_revoked",
          "last_stage",
          "media_content_mismatch",
          "media_expired",
          "media_expires_before_schedule",
          "media_integrity_failed",
          "media_kind_mismatch",
          "media_not_found",
          "media_origins_limit",
          "media_too_large",
          "media_unavailable",
          "media_upload_failed",
          "media_url_blocked",
          "media_url_content_type",
          "media_url_failed",
          "media_url_redirects",
          "media_url_timeout",
          "media_url_unresolvable",
          "member_limit_reached",
          "message_build_failed",
          "message_type_not_supported",
          "mime_type_required",
          "missing_variables",
          "newsletter_not_found",
          "newsletter_request_rejected",
          "no_admin_groups",
          "no_consented_recipients",
          "no_known_message",
          "no_person_for_key",
          "not_acceptable",
          "not_allowed",
          "not_authorized",
          "not_cancelable",
          "not_found",
          "not_group_admin",
          "not_group_member",
          "not_logged_in",
          "not_on_whatsapp",
          "not_supported_by_engine",
          "number_blocked",
          "number_not_connected",
          "number_not_found",
          "number_paused",
          "number_still_linked",
          "numbers_over_limit",
          "operation_failed",
          "operator_name_required",
          "operator_required",
          "opted_in_in_future",
          "options_only_for_select",
          "options_required",
          "organization_key_required",
          "organization_suspended",
          "outcome_unknown",
          "owner_or_admin_required",
          "owner_required",
          "pairing_recovery_required",
          "payload_too_large",
          "picture_not_set",
          "plan_feature_required",
          "post_lookup_failed",
          "post_not_found",
          "privacy_hidden",
          "privacy_token_missing",
          "private_chat_required",
          "provider_rate_limited",
          "provider_rejected",
          "proxy_host_not_allowed",
          "push_name_missing",
          "qr_unavailable",
          "queue_full",
          "range_not_satisfiable",
          "rate_limited",
          "readiness_check_failed",
          "reauth_failed",
          "recipient_not_registered",
          "recipient_unknown",
          "recording_module_required",
          "recording_not_found",
          "recording_not_ready",
          "recording_quantity_exceeded",
          "recording_unavailable",
          "recordings_busy",
          "recordings_unavailable",
          "redelivery_limit_reached",
          "rejected_by_whatsapp",
          "renewal_checkout_unavailable",
          "renewal_conflict",
          "renewal_unavailable",
          "result_expired",
          "retry",
          "scope_denied",
          "self_removal_denied",
          "send_failed",
          "send_prepare_failed",
          "send_unavailable",
          "sender_required",
          "session_disconnected",
          "shortcut_exists",
          "slot_limit_reached",
          "slug_taken",
          "stage_exists",
          "stream_token_expired",
          "stream_token_requires_api_key",
          "tag_exists",
          "target_index_building",
          "target_not_editable",
          "target_not_found",
          "target_not_revocable",
          "team_manager_required",
          "template_name_exists",
          "template_not_found",
          "template_read_only",
          "ticket_already_open",
          "ticket_not_open",
          "ticket_pending",
          "too_many_active_broadcasts",
          "too_many_active_campaigns",
          "too_many_fields",
          "too_many_recipients",
          "too_many_scheduled",
          "too_many_stages",
          "transport_ambiguous",
          "unauthorized",
          "unavailable",
          "unknown_neighbor",
          "unknown_stage",
          "unknown_tag",
          "unsafe_webhook_destination",
          "unsupported_media_type",
          "use_message_routes",
          "user_not_member",
          "voice_note_too_large",
          "voice_note_too_long",
          "webhook_dns_unavailable",
          "webhook_secret_unavailable",
          "workspace_id_required",
          "workspace_slot_limit_reached"
        ],
        "x-enum-descriptions": {
          "account_exists": "Este e-mail já tem conta e o convite de dono não pode criar outra.",
          "addon_change_refused": "A cobrança recusou a mudança do adicional (motivo em `reason`).",
          "after_sequence_requires_instance": "`after_sequence` só vale com um número (`instance_id`), porque a sequência é por número.",
          "already_member": "A pessoa já faz parte da equipe.",
          "already_sent": "O agendamento já foi enviado (o envio está em `message_id`).",
          "api_access_token_required": "O Chatwoot precisa do token de acesso da API para ser ligado.",
          "api_key_active": "A chave ainda está ativa: só uma chave revogada ou expirada pode ser excluída da lista.",
          "api_key_not_active": "A chave foi revogada ou expirou: o nome e as permissões não mudam mais.",
          "audience_empty": "O público não tem membros para exportar.",
          "audience_not_ready": "O público ainda está sendo coletado.",
          "audio_conversion_unavailable": "A conversão de áudio para nota de voz está indisponível no momento.",
          "audio_unreadable": "O arquivo de áudio não pôde ser lido (vazio ou corrompido).",
          "author_not_allowed": "A anotação não pode ser atribuída a essa pessoa com esta chave.",
          "bad_request": "O WhatsApp recusou o pedido do canal como inválido.",
          "before_or_after": "Mover no funil pede `before` ou `after`, não os dois.",
          "billing_read_unavailable": "A leitura da cobrança está indisponível no momento.",
          "billing_role_required": "A chave não age por uma pessoa com papel de cobrança (dono ou financeiro).",
          "billing_unavailable": "A cobrança está indisponível no momento.",
          "call_already_answering": "Outra pessoa já está atendendo esta ligação.",
          "call_ended": "A ligação já terminou; não há mais áudio para conectar.",
          "call_not_ringing": "A ligação não está tocando neste número (já atendida, recusada ou encerrada).",
          "call_quantity_exceeded": "A escolha passa da quantidade de números com ligações contratada.",
          "call_target_not_allowed": "Na fase de testes, só os números de teste cadastrados podem receber ligações.",
          "call_test_numbers_limit": "A lista passa de 20 números de teste diferentes, ou de 40 números diferentes incluídos nos últimos 30 dias.",
          "call_trial_not_enabled": "O piloto de ligações não está ligado nesta conta, então não há números de teste a definir.",
          "calls_not_enabled": "As ligações não estão ligadas para este número.",
          "capacity_unavailable": "A conta não tem vagas de número no plano em vigor.",
          "card_checkout_unavailable": "O pagamento por cartão está indisponível no momento.",
          "carousel_media_mixed": "O carrossel mistura fotos e vídeos; todos os cartões precisam do mesmo tipo.",
          "carousel_media_too_large": "As mídias do carrossel somadas passam do limite.",
          "chatwoot_url_invalid": "O endereço do Chatwoot é inválido ou não é público.",
          "checkout_expired": "O link de pagamento venceu.",
          "checkout_offer_unavailable": "A oferta do checkout não pôde ser montada agora.",
          "checkout_rejected": "O provedor de pagamento recusou o checkout.",
          "checkout_unavailable": "O checkout está indisponível no momento.",
          "collection_failed": "A coleta do público falhou no número.",
          "collection_in_progress": "Já existe uma coleta deste público em andamento.",
          "collection_too_soon": "A coleta foi feita há pouco; há um intervalo mínimo entre coletas.",
          "consent_required": "Há destinatários sem consentimento registrado (`rejected`, `total`).",
          "contact_already_linked": "Este contato já está ligado a essa conversa.",
          "contact_link_not_found": "A ligação entre contato e conversa não existe.",
          "conversation_not_found": "A conversa não existe neste número.",
          "cursor_map_too_large": "O cursor em mapa (`cursor=map`) ficaria grande demais para os números da chave.",
          "cursor_needs_stage": "O `cursor` do funil só vale junto com a etapa (`stage_id`) em que foi gerado.",
          "declaration_required": "Exportar o público exige a declaração de base legal (LGPD).",
          "delivery_in_progress": "A entrega de webhook ainda está na fila (`pending`, `sending` ou `held`).",
          "disconnect_first": "O número ainda está conectado; desconecte antes de excluir.",
          "download_failed": "Não foi possível baixar a mídia recebida do WhatsApp.",
          "draft_limit_reached": "Limite de números em rascunho atingido.",
          "empty_media": "O arquivo enviado está vazio.",
          "endpoint_disabled": "O endereço de webhook foi removido (ou respondeu 410); não pode ser alterado, testado nem receber reenvio.",
          "endpoint_exists": "Já existe um webhook ativo com essa URL nesta área de trabalho.",
          "endpoint_limit_reached": "A área de trabalho chegou ao limite de webhooks do plano.",
          "engine_capability_missing": "O motor do WhatsApp deste número não oferece esta ação.",
          "engine_error": "O número falhou ao executar uma leitura no WhatsApp.",
          "engine_not_connected": "O número não estava conectado ao WhatsApp ao executar a operação.",
          "engine_timeout": "A operação venceu antes de o número executá-la; nada foi feito.",
          "engine_unavailable": "As operações do WhatsApp estão desligadas neste ambiente.",
          "existing_account": "O e-mail convidado já tem conta em outra organização ou o convite pede cadastro novo.",
          "field_exists": "Já existe um campo personalizado com essa chave.",
          "forbidden": "A pessoa da chave não pode fazer esta ação.",
          "forward_media_expired": "A mídia da mensagem a encaminhar expirou.",
          "forward_media_too_large": "A mídia da mensagem a encaminhar passa do limite de envio.",
          "forward_media_unavailable": "A mídia da mensagem a encaminhar não está guardada.",
          "forward_not_allowed": "Essa mensagem não pode ser encaminhada.",
          "forward_not_supported": "Esse tipo de mensagem não pode ser encaminhado.",
          "from_me_required": "Informe `from_me` (se a mensagem alvo é sua ou do contato).",
          "group_announce_only": "O grupo só aceita mensagens de administradores e o número não é admin (em `error_code` do envio).",
          "group_info_unavailable": "As informações do grupo não puderam ser lidas.",
          "group_not_found": "O grupo não existe ou o número não o vê.",
          "groups_not_ready": "A lista de grupos do número ainda está sendo carregada.",
          "groups_unavailable": "A lista de grupos não pôde ser lida no número.",
          "history_import_off": "O número não importa histórico do WhatsApp (desligado em `settings/history`).",
          "idempotency_conflict": "A mesma `Idempotency-Key` já foi usada com outro conteúdo.",
          "idempotency_key_mismatch": "A `Idempotency-Key` do cabeçalho difere da do corpo.",
          "idempotency_key_required": "Esta rota exige `Idempotency-Key`.",
          "image_too_large": "A imagem passa do tamanho aceito.",
          "instance_not_in_workspace": "Algum número em `instance_ids` não é desta área de trabalho (ou foi excluído).",
          "instance_requires_workspace": "Uma chave presa a um número também precisa da área de trabalho dele.",
          "invalid_action": "Ação inválida para esta operação.",
          "invalid_auto_replies": "As respostas automáticas têm um campo inválido (`field`).",
          "invalid_before": "O marcador `before` da leitura é inválido.",
          "invalid_body": "O corpo do upload é inválido.",
          "invalid_broadcast_state": "O envio em grupos não está num estado que permita esta ação.",
          "invalid_call_id": "ID de ligação inválido.",
          "invalid_campaign_state": "A campanha não está num estado que permita esta ação.",
          "invalid_caption": "Legenda inválida.",
          "invalid_color": "Cor inválida.",
          "invalid_count": "Quantidade pedida inválida.",
          "invalid_cursor": "O `cursor` não veio desta rota (ou desta consulta).",
          "invalid_description": "Descrição inválida (vazia ou longa demais).",
          "invalid_duration": "Duração inválida.",
          "invalid_ephemeral_timer": "Tempo de mensagens temporárias inválido.",
          "invalid_expiration": "Validade inválida.",
          "invalid_expiry": "`expires_at` inválido (no passado ou longe demais).",
          "invalid_field_value": "O valor não serve para o campo personalizado (`field`).",
          "invalid_file_name": "O nome de arquivo (`X-File-Name`) é inválido.",
          "invalid_group_jid": "JID de grupo inválido.",
          "invalid_group_name": "Nome de grupo inválido (vazio ou longo demais).",
          "invalid_groups": "Lista de grupos inválida.",
          "invalid_idempotency_key": "`Idempotency-Key` com formato inválido.",
          "invalid_image": "A imagem não pôde ser lida ou não é de um tipo aceito.",
          "invalid_input": "O pedido não segue o formato da rota (corpo, parâmetros ou consulta).",
          "invalid_instance_state": "O número não está num estado que permita esta ação (ex.: conectar um número excluído ou arquivado).",
          "invalid_invite": "Convite de grupo inválido.",
          "invalid_invite_code": "Código de convite inválido.",
          "invalid_jid": "JID inválido (no caminho ou no corpo).",
          "invalid_json": "O corpo não é JSON válido.",
          "invalid_label_id": "ID de etiqueta inválido.",
          "invalid_last_event_id": "`Last-Event-ID` (ou `last_event_id`) não está num formato aceito.",
          "invalid_media_kind": "Tipo de mídia (`kind`) inválido no upload.",
          "invalid_media_url": "A URL da mídia é inválida.",
          "invalid_member_add_mode": "Modo de entrada de participantes inválido.",
          "invalid_message": "A mensagem montada pelo modelo é inválida.",
          "invalid_message_id": "ID de mensagem inválido.",
          "invalid_message_ids": "Lista de IDs de mensagem inválida.",
          "invalid_name": "Nome inválido.",
          "invalid_newsletter_jid": "JID de canal inválido.",
          "invalid_newsletter_name": "Nome de canal inválido.",
          "invalid_or_expired_invitation": "O convite é inválido ou venceu.",
          "invalid_origin": "Não é uma origem exata aceita: use `https://host[:porta]` (ou `http://localhost[:porta]` e `http://127.0.0.1[:porta]` para desenvolvimento), sem caminho, `?`, `#`, usuário e senha ou `*`.",
          "invalid_participant": "Participante inválido.",
          "invalid_participants": "Lista de participantes inválida.",
          "invalid_payload": "O corpo recebido não tem o formato esperado.",
          "invalid_phone": "Telefone inválido.",
          "invalid_placeholder": "Variável inválida ou desconhecida no texto (ex.: `{{nome}}`).",
          "invalid_privacy_value": "Valor de privacidade inválido.",
          "invalid_proxy_url": "A URL do proxy é inválida.",
          "invalid_reaction": "Reação inválida.",
          "invalid_schedule": "Data de agendamento fora da janela permitida.",
          "invalid_sender_result": "Resultado inesperado do envio; o desfecho é incerto (em `error_code` do envio).",
          "invalid_server_id": "ID de publicação do canal inválido.",
          "invalid_server_ids": "Lista de IDs de publicação inválida.",
          "invalid_since": "Data `since` inválida.",
          "invalid_status_style": "Estilo do status (cor ou fonte) inválido (em `error_code` do envio).",
          "invalid_text": "Texto inválido (vazio ou longo demais).",
          "invalid_timer": "Tempo inválido.",
          "invalid_timestamp": "Data/hora inválida.",
          "invalid_token": "O token OAuth não foi emitido para este recurso.",
          "invitation_closed": "O convite já foi aceito, cancelado ou venceu.",
          "invitation_email_mismatch": "A sessão é de um e-mail diferente do convidado.",
          "invitation_idempotency_conflict": "A mesma chave de pedido já criou um convite diferente.",
          "invitation_not_found": "O convite não existe ou o link é inválido.",
          "invitation_recipient_mismatch": "O convite é para outra pessoa.",
          "invite_expired": "O convite do grupo venceu.",
          "invite_not_allowed": "O número não pode gerar ou usar este convite (não é admin ou o grupo não permite).",
          "invite_not_requested": "Não há pedido de entrada desta pessoa no grupo.",
          "invite_revoked": "O convite do grupo foi revogado.",
          "last_stage": "O funil precisa de ao menos uma etapa.",
          "media_content_mismatch": "O conteúdo do arquivo não bate com o tipo informado.",
          "media_expired": "A mídia expirou no WhatsApp.",
          "media_expires_before_schedule": "A mídia guardada vence antes da data agendada.",
          "media_integrity_failed": "O arquivo guardado não passou na conferência de integridade.",
          "media_kind_mismatch": "A mídia guardada é de outro tipo que o do envio.",
          "media_not_found": "A mídia não existe, expirou ou não é deste número.",
          "media_origins_limit": "A conta já tem 10 origens liberadas para o áudio no navegador.",
          "media_too_large": "O arquivo passa do limite (16 MiB no upload; limites do WhatsApp por tipo).",
          "media_unavailable": "A mídia do envio não estava disponível na hora de enviar (em `error_code` do envio).",
          "media_upload_failed": "O envio da mídia ao WhatsApp falhou antes da mensagem sair (em `error_code` do envio).",
          "media_url_blocked": "A URL da mídia aponta para um destino não permitido (rede privada).",
          "media_url_content_type": "A URL respondeu com um tipo de conteúdo não aceito.",
          "media_url_failed": "Não foi possível baixar a mídia da URL.",
          "media_url_redirects": "A URL da mídia redirecionou vezes demais.",
          "media_url_timeout": "A URL da mídia demorou demais para responder.",
          "media_url_unresolvable": "O endereço da URL da mídia não foi encontrado (DNS).",
          "member_limit_reached": "A equipe chegou ao limite de pessoas do plano.",
          "message_build_failed": "A mensagem não pôde ser montada para o WhatsApp (em `error_code` do envio).",
          "message_type_not_supported": "O tipo de mensagem não é suportado pelo motor (em `error_code` do envio).",
          "mime_type_required": "Falta o tipo do arquivo (`Content-Type`).",
          "missing_variables": "Faltam valores para variáveis do modelo (`missing`).",
          "newsletter_not_found": "O canal não existe ou não está visível.",
          "newsletter_request_rejected": "O WhatsApp recusou o pedido ao canal.",
          "no_admin_groups": "Nenhum dos grupos escolhidos é administrado pelo número.",
          "no_consented_recipients": "Nenhum destinatário tem consentimento registrado.",
          "no_known_message": "Não há mensagem guardada nessa conversa para ancorar o pedido de histórico.",
          "no_person_for_key": "A ação precisa de uma pessoa e a chave não age por ninguém.",
          "not_acceptable": "O WhatsApp recusou o pedido ao canal (formato não aceito).",
          "not_allowed": "O WhatsApp não permite esta ação no canal.",
          "not_authorized": "O WhatsApp não autorizou a leitura (privacidade do contato).",
          "not_cancelable": "O agendamento não pode mais ser cancelado (`state`).",
          "not_found": "Não existe, ou a chave não alcança esse recurso (área de trabalho ou número de outra chave).",
          "not_group_admin": "A ação exige que o número seja admin do grupo.",
          "not_group_member": "O número não participa do grupo.",
          "not_logged_in": "O número não está logado no WhatsApp.",
          "not_on_whatsapp": "O telefone não tem WhatsApp.",
          "not_supported_by_engine": "O WhatsApp Web não oferece este recurso.",
          "number_blocked": "O WhatsApp bloqueou o número; não dá para reconectar enquanto o bloqueio vale.",
          "number_not_connected": "O número não está conectado ao WhatsApp agora.",
          "number_not_found": "O número não existe nesta conta.",
          "number_paused": "Outra sessão do WhatsApp assumiu o número ou a versão foi recusada; reconectar pelo QR não resolve agora.",
          "number_still_linked": "O número continua ligado ao WhatsApp (conectado, reconectando ou fora do ar); não precisa ler o QR de novo.",
          "numbers_over_limit": "A conta tem mais números que o plano permite; envios estão pausados.",
          "operation_failed": "A operação falhou no WhatsApp sem motivo específico.",
          "operator_name_required": "O número exige o nome de quem envia (assinatura obrigatória).",
          "operator_required": "A ação precisa de uma pessoa operadora e a chave não age por ninguém.",
          "opted_in_in_future": "A data de consentimento está no futuro.",
          "options_only_for_select": "Opções só valem para campos de seleção.",
          "options_required": "Campos de seleção precisam de opções.",
          "organization_key_required": "Rota de administração da conta: só uma chave da organização inteira serve; esta chave está presa a uma área de trabalho ou a um número.",
          "organization_suspended": "A conta está suspensa ou encerrada; nenhuma rota responde.",
          "outcome_unknown": "O WhatsApp pode ter aplicado a mudança ou não (resultado incerto).",
          "owner_or_admin_required": "Só dono ou administrador pode fazer esta ação.",
          "owner_required": "Só o dono da conta pode fazer esta ação.",
          "pairing_recovery_required": "O número precisa ser recuperado antes de parear de novo.",
          "payload_too_large": "O corpo passa do limite da rota.",
          "picture_not_set": "O contato ou grupo não tem foto.",
          "plan_feature_required": "O plano da conta não inclui este recurso (API ou MCP).",
          "post_lookup_failed": "A publicação do canal não pôde ser localizada agora.",
          "post_not_found": "A publicação do canal não existe.",
          "privacy_hidden": "A privacidade do contato esconde esta informação.",
          "privacy_token_missing": "Falta o token de privacidade do contato para esta leitura.",
          "private_chat_required": "Esta ação só vale em conversa privada (não em grupo).",
          "provider_rate_limited": "O provedor de pagamento limitou os pedidos.",
          "provider_rejected": "O WhatsApp recusou o envio (em `error_code` do envio).",
          "proxy_host_not_allowed": "O host do proxy não é permitido (rede privada).",
          "push_name_missing": "O contato não tem nome público.",
          "qr_unavailable": "O QR code ainda não está disponível.",
          "queue_full": "A fila do número já tem os envios aguardando que o plano permite.",
          "range_not_satisfiable": "O intervalo `Range` pedido está fora do arquivo.",
          "rate_limited": "Limite de pedidos ou de envios atingido.",
          "readiness_check_failed": "A checagem antes do envio falhou e nada saiu (em `error_code` do envio).",
          "reauth_failed": "A confirmação de identidade falhou.",
          "recipient_not_registered": "O destinatário não tem WhatsApp (em `error_code` do envio).",
          "recipient_unknown": "O Chatwoot pediu envio para um contato que o FlowZap não reconhece.",
          "recording_module_required": "O número não tem o módulo de gravações.",
          "recording_not_found": "A ligação não tem gravação disponível; `reason` diz por quê: `not_recorded`, `failed`, `expired` ou `deleted`.",
          "recording_not_ready": "A gravação ainda está gravando ou sendo processada (`recording_state`: `recording` ou `processing`).",
          "recording_quantity_exceeded": "A escolha passa da quantidade de números com gravação contratada.",
          "recording_unavailable": "A gravação não pôde ser lida agora.",
          "recordings_busy": "Muitos downloads de gravação ao mesmo tempo.",
          "recordings_unavailable": "As gravações estão indisponíveis no momento.",
          "redelivery_limit_reached": "A entrega de webhook já teve 10 rodadas.",
          "rejected_by_whatsapp": "O WhatsApp recusou o pedido.",
          "renewal_checkout_unavailable": "Não há checkout de renovação disponível para esse ciclo.",
          "renewal_conflict": "A renovação já mudou enquanto o pedido rodava.",
          "renewal_unavailable": "A renovação está indisponível no momento.",
          "result_expired": "O resultado da operação já foi apagado (dados pessoais ficam 1 hora).",
          "retry": "Conflito momentâneo ao gravar; nada foi alterado.",
          "scope_denied": "A chave não tem o escopo desta rota.",
          "self_removal_denied": "A pessoa não pode remover a si mesma por aqui.",
          "send_failed": "O agendamento falhou ao enviar.",
          "send_prepare_failed": "O envio falhou antes de sair do aparelho (em `error_code` do envio).",
          "send_unavailable": "O envio não está liberado para a conta ou o número agora (assinatura ou vaga).",
          "sender_required": "Informe quem enviou a mensagem alvo (`sender`), obrigatório em grupos.",
          "session_disconnected": "O número desconectou antes de enviar; nada saiu (em `error_code` do envio).",
          "shortcut_exists": "Já existe uma resposta rápida com esse atalho.",
          "slot_limit_reached": "Não há vaga livre de número no plano.",
          "slug_taken": "O endereço (slug) do link já está em uso.",
          "stage_exists": "Já existe uma etapa com esse nome.",
          "stream_token_expired": "O token de fluxo (`?token=`) venceu (vale 5 minutos).",
          "stream_token_requires_api_key": "O token de fluxo só é emitido para chave de API (`fzk_`), não para token OAuth (`fzo_`).",
          "tag_exists": "Já existe uma etiqueta com esse nome.",
          "target_index_building": "O índice para localizar a mensagem alvo ainda está sendo montado.",
          "target_not_editable": "Só mensagens enviadas pelo número podem ser editadas.",
          "target_not_found": "A mensagem alvo não foi encontrada neste número.",
          "target_not_revocable": "Mensagem de outra pessoa só é apagada para todos em grupo, por admin.",
          "team_manager_required": "Só quem administra a equipe pode fazer esta ação.",
          "template_name_exists": "Já existe um modelo com esse nome.",
          "template_not_found": "O modelo não existe.",
          "template_read_only": "Modelo da organização não pode ser alterado por uma chave presa a área de trabalho.",
          "ticket_already_open": "Já há um atendimento aberto para essa conversa.",
          "ticket_not_open": "O atendimento não está aberto.",
          "ticket_pending": "O atendimento está pendente; retire a pendência antes.",
          "too_many_active_broadcasts": "Limite de envios em grupos ativos ao mesmo tempo.",
          "too_many_active_campaigns": "Limite de campanhas ativas ao mesmo tempo.",
          "too_many_fields": "Limite de campos personalizados atingido.",
          "too_many_recipients": "Destinatários demais para uma campanha.",
          "too_many_scheduled": "Limite de agendamentos pendentes atingido.",
          "too_many_stages": "Limite de etapas do funil atingido.",
          "transport_ambiguous": "A conexão falhou durante o envio: a mensagem pode ter saído (em `error_code`, estado `unknown`).",
          "unauthorized": "Chave ausente, inválida, revogada ou vencida.",
          "unavailable": "O serviço está indisponível no momento.",
          "unknown_neighbor": "O vizinho informado para mover no funil não existe.",
          "unknown_stage": "Etapa do funil desconhecida.",
          "unknown_tag": "Etiqueta de lead desconhecida.",
          "unsafe_webhook_destination": "A URL do webhook aponta para destino não permitido (rede privada, porta ou esquema).",
          "unsupported_media_type": "Tipo de arquivo não aceito para esse envio.",
          "use_message_routes": "Esse ID é de mensagem; leia pelas rotas de mensagem.",
          "user_not_member": "A pessoa indicada não é da equipe.",
          "voice_note_too_large": "A nota de voz convertida passa do limite.",
          "voice_note_too_long": "A nota de voz é longa demais.",
          "webhook_dns_unavailable": "O DNS do endereço do webhook não respondeu agora.",
          "webhook_secret_unavailable": "O segredo do webhook não pôde ser aberto no servidor.",
          "workspace_id_required": "Falta `workspace_id` na consulta.",
          "workspace_slot_limit_reached": "A área de trabalho chegou ao limite de números."
        }
      },
      "EventType": {
        "type": "string",
        "enum": [
          "message.queued",
          "message.dispatching",
          "message.provider_accepted",
          "message.delivered",
          "message.read",
          "message.failed",
          "message.unknown",
          "message.expired",
          "message.receipt",
          "message.received",
          "instance.paired",
          "instance.connection",
          "instance.reachout_timelock",
          "presence.update",
          "chat.presence",
          "group.update",
          "group.joined",
          "contact.picture",
          "contact.update",
          "contact.blocklist",
          "call.offer",
          "call.accept",
          "call.terminate",
          "call.reject",
          "call.started",
          "call.ringing",
          "call.answered",
          "call.media_connected",
          "call.ended",
          "label.edit",
          "label.chat",
          "label.message",
          "chat.update",
          "history.sync",
          "newsletter.join",
          "newsletter.leave",
          "newsletter.mute_change",
          "newsletter.live_update",
          "ticket.opened",
          "ticket.resolved",
          "ticket.reopened",
          "ticket.assigned",
          "ticket.pending_set",
          "ticket.pending_cleared",
          "lead.stage_changed",
          "csat.answered",
          "call.recording_ready",
          "call.recording_deleted",
          "call.recording_failed"
        ],
        "description": "Catálogo aceito no filtro `types`. `message.canceled` (envio cancelado na fila) também é entregue por webhook e SSE, mas ainda não é aceito no filtro."
      },
      "ExportDeclaration": {
        "type": "object",
        "required": [
          "version",
          "text"
        ],
        "properties": {
          "version": {
            "type": "string"
          },
          "text": {
            "type": "string"
          }
        }
      },
      "ExportInput": {
        "type": "object",
        "required": [
          "format",
          "declaration_accepted"
        ],
        "properties": {
          "format": {
            "type": "string",
            "enum": [
              "meta",
              "google",
              "csv"
            ],
            "description": "`csv`: planilha legível para eventos e listas (UTF-8 com BOM, separador `;`, linhas CRLF, aspas RFC 4180; colunas `telefone` como texto `55 41 99961-2626` (país, DDD e número; só os dígitos dão o E.164), `nome`, `grupos` separados por ` | `, `grupo_administrado` sim/não, `primeira_vez` e `ultima_vez` em dd/mm/aaaa HH:MM de Brasília; nome ou grupo que começa com `=`, `+`, `-`, `@`, tab ou CR recebe um `'` na frente contra injeção de fórmula). `meta`: Público Personalizado (cabeçalho `phone,fn,ln,country`; telefone só com dígitos e DDI, nome sem acento e pontuação, país `br` só para números +55; tudo em SHA-256 hex minúsculo). `google`: Customer Match (cabeçalho `Phone`; telefone E.164 com `+` em SHA-256 hex), com o público inteiro."
          },
          "declaration_accepted": {
            "type": "boolean",
            "description": "Precisa ser `true` em toda exportação: a pessoa aceita o texto de `export_declarations[format]` (a planilha `csv` tem declaração própria; a versão fica no histórico). Sem isso, 422 `declaration_required`."
          }
        },
        "additionalProperties": false
      },
      "GroupBroadcast": {
        "type": "object",
        "required": [
          "id",
          "name",
          "state",
          "total_groups",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "message_type": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "scheduled",
              "running",
              "paused",
              "paused_disconnected",
              "paused_by_safety",
              "completed",
              "canceled"
            ]
          },
          "pause_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "`manual`, `number_not_connected`, `send_unavailable`, `failure_rate` (mais de 20% dos últimos 50 envios falharam), `reachout_timelock`."
          },
          "scheduled_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "next_send_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "delay_ms": {
            "type": "object",
            "properties": {
              "min": {
                "type": "integer"
              },
              "max": {
                "type": "integer"
              }
            }
          },
          "daily_limit": {
            "type": "integer"
          },
          "window": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/CampaignWindow"
              },
              {
                "type": "null"
              }
            ]
          },
          "total_groups": {
            "type": "integer"
          },
          "skipped_not_admin": {
            "type": "integer",
            "description": "Grupos pedidos que ficaram de fora (não administrados ou não encontrados)."
          },
          "counts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Grupos por situação (`pending`, `accepted`, `failed`, `canceled`)."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "GroupBroadcastReport": {
        "allOf": [
          {
            "$ref": "#/components/schemas/GroupBroadcast"
          },
          {
            "type": "object",
            "properties": {
              "groups": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "group_jid": {
                      "$ref": "#/components/schemas/GroupJid"
                    },
                    "group_name": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "pending",
                        "accepted",
                        "failed",
                        "canceled"
                      ]
                    },
                    "error_code": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Por que falhou: `not_group_admin` e `group_not_found` vêm da conferência feita antes de cada grupo; os demais, do envio."
                    },
                    "message_id": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uuid",
                      "description": "A mensagem do grupo (`GET …/messages/{id}`)."
                    },
                    "message_state": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "`queued`, `provider_accepted`, `delivered`, `read`, `failed`…"
                    },
                    "sent_at": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "GroupImageInput": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "image"
            ],
            "properties": {
              "image": {
                "type": "string",
                "format": "byte",
                "maxLength": 955736,
                "description": "JPEG em base64, até 700 KiB."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": [
              "media_id"
            ],
            "properties": {
              "media_id": {
                "type": "string",
                "format": "uuid",
                "description": "Mídia JPEG enviada antes por `POST .../media` (mesmo número)."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "GroupInviteCode": {
        "type": "string",
        "description": "Código do convite ou o link completo `https://chat.whatsapp.com/<código>`."
      },
      "GroupInviteLink": {
        "type": "object",
        "required": [
          "jid",
          "link",
          "code"
        ],
        "properties": {
          "jid": {
            "type": "string"
          },
          "link": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "GroupInviteMessage": {
        "type": "object",
        "required": [
          "jid",
          "phone",
          "message_id",
          "expires_at",
          "sent_at"
        ],
        "properties": {
          "jid": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "message_id": {
            "type": "string"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "sent_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "GroupInviteMessageInput": {
        "type": "object",
        "required": [
          "phone",
          "code",
          "expires_at"
        ],
        "properties": {
          "phone": {
            "$ref": "#/components/schemas/E164"
          },
          "code": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{6,64}$",
            "description": "`add_request.code` devolvido para essa pessoa por `POST …/groups/{jid}/participants` com `action: add` neste grupo e por este número (últimos 8 dias); outro código, telefone ou grupo é recusado com 422 `invite_not_requested`."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "`add_request.expires_at` da mesma resposta. Vale o vencimento registrado nessa resposta, quando houver; um convite vencido é recusado (`invite_expired`)."
          },
          "caption": {
            "type": "string",
            "maxLength": 200,
            "description": "Texto curto opcional junto do convite."
          }
        },
        "additionalProperties": false
      },
      "GroupJid": {
        "type": "string",
        "pattern": "^\\d{5,40}(-\\d+)?@g\\.us$",
        "description": "JID de grupo ou comunidade (ex.: `120363025246125888@g.us`)."
      },
      "GroupParticipant": {
        "type": "object",
        "required": [
          "jid",
          "phone",
          "phone_source",
          "lid",
          "is_admin",
          "is_super_admin",
          "is_me",
          "masked_phone"
        ],
        "properties": {
          "jid": {
            "type": "string",
            "description": "JID principal (telefone `…@s.whatsapp.net` ou LID `…@lid`)."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Telefone E.164; `null` quando nem o grupo nem o número conhecem o telefone. O telefone que o grupo esconde e só o número conhece (`phone_source: lid_map`) vem `null` (com `masked_phone`) para chaves sem o escopo `audiences:export`."
          },
          "phone_source": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "jid",
              "server",
              "lid_map",
              null
            ],
            "description": "De onde veio o telefone: `jid` (o JID é o telefone), `server` (o WhatsApp mandou junto do LID), `lid_map` (o número já conhecia esse LID de conversas ou consultas anteriores)."
          },
          "lid": {
            "type": [
              "string",
              "null"
            ],
            "description": "LID da pessoa (`…@lid`), quando conhecido."
          },
          "is_admin": {
            "type": "boolean"
          },
          "is_super_admin": {
            "type": "boolean",
            "description": "Dono ou criador do grupo."
          },
          "is_me": {
            "type": "boolean",
            "description": "É o próprio número."
          },
          "display_name": {
            "type": "string",
            "description": "Nome da pessoa na agenda ou no perfil, quando o número conhece. Antes trazia o telefone mascarado, que agora está em `masked_phone`."
          },
          "masked_phone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Telefone mascarado pelo WhatsApp para quem esconde o número (ex. `+55∙∙∙∙∙∙∙∙80`)."
          },
          "error": {
            "type": "integer"
          }
        },
        "additionalProperties": false
      },
      "GroupParticipantResult": {
        "type": "object",
        "required": [
          "jid",
          "phone",
          "status"
        ],
        "properties": {
          "jid": {
            "type": "string"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "integer",
            "description": "200 quando aplicado; senão, o código que o WhatsApp devolveu para essa pessoa."
          },
          "add_request": {
            "type": "object",
            "required": [
              "code",
              "expires_at"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "expires_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "GroupParticipantsInput": {
        "type": "object",
        "required": [
          "action",
          "participants"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "add",
              "remove",
              "promote",
              "demote"
            ]
          },
          "participants": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/E164"
                },
                {
                  "type": "string",
                  "pattern": "^\\d{5,20}@(s\\.whatsapp\\.net|lid)$"
                }
              ]
            },
            "minItems": 1,
            "maxItems": 50
          }
        },
        "additionalProperties": false
      },
      "GroupParticipantsUpdate": {
        "type": "object",
        "required": [
          "jid",
          "action",
          "participants"
        ],
        "properties": {
          "jid": {
            "type": "string"
          },
          "action": {
            "type": "string"
          },
          "participants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GroupParticipantResult"
            }
          }
        },
        "additionalProperties": false
      },
      "GroupReceipts": {
        "type": "object",
        "required": [
          "data",
          "group",
          "summary"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "participant",
                "jid",
                "delivered_at",
                "read_at"
              ],
              "properties": {
                "participant": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Telefone (E.164), mascarado quando o grupo não o mostra e a chave não tem `audiences:export`; `null` se desconhecido."
                },
                "jid": {
                  "type": "string",
                  "description": "ID do participante no WhatsApp (telefone ou ID oculto), sem aparelho."
                },
                "delivered_at": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "read_at": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                }
              },
              "additionalProperties": false
            }
          },
          "group": {
            "type": "boolean",
            "description": "`false`: mensagem direta (lista vazia)."
          },
          "summary": {
            "type": "object",
            "required": [
              "delivered",
              "read"
            ],
            "properties": {
              "delivered": {
                "type": "integer"
              },
              "read": {
                "type": "integer"
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "GroupRequestsInput": {
        "type": "object",
        "required": [
          "action",
          "participants"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "approve",
              "reject"
            ]
          },
          "participants": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/E164"
                },
                {
                  "type": "string",
                  "pattern": "^\\d{5,20}@(s\\.whatsapp\\.net|lid)$"
                }
              ]
            },
            "minItems": 1,
            "maxItems": 50
          }
        },
        "additionalProperties": false
      },
      "GroupSummary": {
        "type": "object",
        "required": [
          "jid",
          "name",
          "topic",
          "owner",
          "owner_phone",
          "created_at",
          "participant_count",
          "announce",
          "locked",
          "join_approval",
          "member_add_mode",
          "ephemeral_seconds",
          "is_community",
          "parent_jid",
          "is_default_subgroup",
          "suspended",
          "addressing_mode",
          "is_admin"
        ],
        "properties": {
          "jid": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "topic": {
            "type": "string",
            "description": "Descrição do grupo."
          },
          "owner": {
            "type": [
              "string",
              "null"
            ]
          },
          "owner_phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "participant_count": {
            "type": "integer",
            "minimum": 0
          },
          "addressing_mode": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "pn",
              "lid",
              null
            ],
            "description": "`lid` quando o WhatsApp lista os participantes por LID; telefones podem vir de `lid_map` ou faltar."
          },
          "is_admin": {
            "type": "boolean",
            "description": "O próprio número é administrador do grupo."
          },
          "announce": {
            "type": "boolean",
            "description": "Só administradores enviam mensagens."
          },
          "locked": {
            "type": "boolean",
            "description": "Só administradores editam os dados do grupo."
          },
          "join_approval": {
            "type": "boolean",
            "description": "Entrada pelo link precisa de aprovação."
          },
          "member_add_mode": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "admins",
              "all",
              null
            ]
          },
          "ephemeral_seconds": {
            "type": "integer",
            "minimum": 0
          },
          "is_community": {
            "type": "boolean"
          },
          "parent_jid": {
            "type": [
              "string",
              "null"
            ]
          },
          "is_default_subgroup": {
            "type": "boolean"
          },
          "suspended": {
            "type": "boolean"
          },
          "participants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GroupParticipant"
            }
          }
        },
        "additionalProperties": false
      },
      "HistoryImport": {
        "type": "object",
        "description": "Importação do histórico que o celular manda ao conectar o número.",
        "required": [
          "enabled"
        ],
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "`true` (padrão): o histórico automático é guardado."
          }
        },
        "additionalProperties": false
      },
      "HistoryMedia": {
        "type": [
          "object",
          "null"
        ],
        "description": "`inbound`: baixe por `GET …/inbound/{id}/media`; `upload`: por `GET …/media/{id}/content` (enquanto o upload existir, 48 horas).",
        "required": [
          "source",
          "id",
          "mime_type",
          "file_name"
        ],
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "inbound",
              "upload"
            ]
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "mime_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "file_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "size_bytes": {
            "type": "integer"
          }
        },
        "additionalProperties": false
      },
      "InboundMessage": {
        "description": "Mensagem recebida, decifrada. Pode trazer campos extras conforme o tipo (mídia, localização, reação...).",
        "allOf": [
          {
            "$ref": "#/components/schemas/InboundMessageBase"
          },
          {
            "$ref": "#/components/schemas/InboundMessageExtras"
          }
        ]
      },
      "InboundMessageBase": {
        "type": "object",
        "required": [
          "id",
          "workspace_id",
          "instance_id",
          "received_at",
          "message_id",
          "chat_jid",
          "sender_jid",
          "text",
          "from_me",
          "group",
          "observed_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "instance_id": {
            "type": "string",
            "format": "uuid"
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          },
          "message_id": {
            "type": "string"
          },
          "chat_jid": {
            "type": "string"
          },
          "sender_jid": {
            "type": "string"
          },
          "chat_alt_jid": {
            "type": "string"
          },
          "push_name": {
            "type": "string"
          },
          "text": {
            "type": [
              "string",
              "null"
            ]
          },
          "from_me": {
            "type": "boolean"
          },
          "group": {
            "type": "boolean"
          },
          "observed_at": {
            "type": "string",
            "format": "date-time"
          },
          "kind": {
            "type": "string",
            "description": "Tipo da mensagem (text, image, edit, revoke, event, pin, call_log, unknown...)."
          },
          "unknown_type": {
            "type": "string",
            "description": "Só em kind unknown: o nome do tipo no WhatsApp (ex.: productMessage), sem conteúdo."
          },
          "view_once": {
            "type": "boolean",
            "description": "Enviada como visualização única; a mídia não fica disponível."
          },
          "revoked": {
            "$ref": "#/components/schemas/MessageRevoked"
          },
          "edits": {
            "type": "array",
            "description": "Versões posteriores vistas no WhatsApp, da mais antiga à mais nova; `text` continua sendo o original.",
            "items": {
              "$ref": "#/components/schemas/MessageEdit"
            }
          },
          "applied": {
            "type": "boolean",
            "description": "Só numa edição ou exclusão cuja mensagem alvo está na leitura: true se marcou o alvo, false se foi ignorada (não veio de quem enviou o alvo ou chegou fora do prazo)."
          },
          "revoked_from_me": {
            "type": "boolean",
            "description": "Só em kind revoke: a chave do pedido, do lado de quem apagou — true quando aponta para uma mensagem dele mesmo."
          },
          "revoked_participant": {
            "type": "string",
            "description": "Só em kind revoke de grupo: a quem pertence a mensagem apagada (JID sem aparelho), quando um administrador apaga a de outra pessoa."
          },
          "edited_from_me": {
            "type": "boolean",
            "description": "Só em kind edit: a chave do pedido, do lado de quem editou."
          },
          "edited_participant": {
            "type": "string",
            "description": "Só em kind edit de grupo, quando a chave traz o participante (JID sem aparelho)."
          }
        }
      },
      "InboundMessageExtras": {
        "type": "object",
        "description": "Campos que uma mensagem recebida pode trazer conforme o tipo (complementa `InboundMessage`). Os campos de contexto e formato (`quoted_participant`, `mentions`, `forwarded`, `forwarding_score`, `ptt`, `width`, `height`, `duration_seconds`, `has_thumbnail`) só existem nas mensagens guardadas a partir desta versão do motor; as anteriores não são reprocessadas.",
        "properties": {
          "caption": {
            "type": "string"
          },
          "mime_type": {
            "type": "string"
          },
          "file_name": {
            "type": "string"
          },
          "size_bytes": {
            "type": "integer"
          },
          "has_media": {
            "type": "boolean",
            "description": "A mídia pode ser baixada por `GET …/inbound/{inboxId}/media`."
          },
          "quoted_message_id": {
            "type": "string"
          },
          "quoted_text": {
            "type": "string",
            "description": "Até 200 caracteres do texto citado."
          },
          "quoted_participant": {
            "type": "string",
            "description": "Quem escreveu a mensagem citada (JID sem aparelho)."
          },
          "mentions": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "string"
            },
            "description": "JIDs mencionados (telefone ou LID), sem aparelho."
          },
          "forwarded": {
            "type": "boolean"
          },
          "forwarding_score": {
            "type": "integer"
          },
          "ptt": {
            "type": "boolean",
            "description": "Áudio gravado como mensagem de voz."
          },
          "ptv": {
            "type": "boolean",
            "description": "Vídeo redondo (recado em vídeo)."
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "duration_seconds": {
            "type": "integer"
          },
          "has_thumbnail": {
            "type": "boolean"
          },
          "reaction": {
            "type": "object",
            "properties": {
              "message_id": {
                "type": "string"
              },
              "emoji": {
                "type": "string",
                "description": "Vazio quando a reação foi removida."
              }
            }
          },
          "location": {
            "type": "object",
            "properties": {
              "lat": {
                "type": "number"
              },
              "lng": {
                "type": "number"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "edited_message_id": {
            "type": "string"
          },
          "revoked_message_id": {
            "type": "string"
          },
          "album": {
            "type": "object",
            "properties": {
              "images": {
                "type": "integer"
              },
              "videos": {
                "type": "integer"
              }
            }
          },
          "event": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "start_at": {
                "type": "string"
              },
              "location": {
                "type": "string"
              },
              "canceled": {
                "type": "boolean"
              }
            }
          },
          "pin": {
            "type": "object",
            "properties": {
              "message_id": {
                "type": "string"
              },
              "pinned": {
                "type": "boolean"
              }
            }
          },
          "poll_vote": {
            "type": "object",
            "properties": {
              "message_id": {
                "type": "string"
              }
            }
          },
          "call_log": {
            "type": "object",
            "properties": {
              "video": {
                "type": "boolean"
              },
              "outcome": {
                "type": "string"
              },
              "duration_secs": {
                "type": "integer"
              }
            }
          },
          "buttons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Em kind buttons/list: os rótulos que a pessoa pode tocar."
          },
          "expiration_secs": {
            "type": "integer",
            "description": "Em kind ephemeral: o novo prazo das mensagens temporárias; 0 desliga."
          }
        }
      },
      "Instance": {
        "type": "object",
        "required": [
          "id",
          "organization_id",
          "workspace_id",
          "name",
          "tags",
          "state"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "organization_id": {
            "type": "string",
            "format": "uuid"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "state": {
            "type": "string",
            "enum": [
              "draft",
              "provisioning",
              "active",
              "archived",
              "deleted"
            ]
          }
        },
        "additionalProperties": false
      },
      "InstanceConnectInput": {
        "type": "object",
        "properties": {
          "phone": {
            "$ref": "#/components/schemas/E164",
            "description": "Pareamento por código no telefone: **não suportado** (responde 501)."
          }
        },
        "additionalProperties": false
      },
      "InstanceDeleted": {
        "type": "object",
        "required": [
          "id",
          "state",
          "canceled_messages"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "deleted"
            ]
          },
          "canceled_messages": {
            "type": "integer",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "InstanceRenamed": {
        "type": "object",
        "required": [
          "id",
          "name",
          "state"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "state": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "InstanceRenameInput": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          }
        },
        "additionalProperties": false
      },
      "InstanceStatus": {
        "type": "object",
        "required": [
          "id",
          "name",
          "state",
          "session_state",
          "connected",
          "phone_masked",
          "worker_alive",
          "lease_until",
          "reservation_state",
          "reservation_expires_at",
          "created_at",
          "disconnect_reason",
          "last_connection_event"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "draft",
              "provisioning",
              "active",
              "archived",
              "deleted"
            ]
          },
          "session_state": {
            "type": [
              "string",
              "null"
            ],
            "description": "Situação da sessão (`session_state`): `unpaired`, `pairing`, `connected`, `reconnecting`, `offline`, `needs_pairing`, `revoked`, `blocked`, `paused`. A lista de números resume a mesma coisa em `session_status` (tabela em `GET …/status`)."
          },
          "connected": {
            "type": "boolean",
            "description": "Número ativo, sessão conectada e worker vivo."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Telefone completo (E.164) da conta de WhatsApp conectada a este número — o número da própria empresa, não de um contato. Só aparece para chaves com `instances:read`; `null` quando o número nunca conectou. Nunca é deduzido de um LID.",
            "examples": [
              "+5511912345678"
            ]
          },
          "phone_masked": {
            "type": [
              "string",
              "null"
            ],
            "description": "Telefone mascarado, ex.: `+55 11 9****-1234`."
          },
          "disconnect_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Por que o número não está conectado: `logged_out` (o celular desconectou o aparelho; conecte de novo pelo QR), `temporary_ban` (bloqueio temporário do WhatsApp; veja `last_connection_event.ban_expires_at`), `disconnected` (queda de conexão; o FlowZap tenta reconectar), `stream_replaced` (outra sessão do WhatsApp Web assumiu), `client_outdated` (versão recusada pelo WhatsApp), `worker_unavailable` (o WhatsApp não desconectou, mas o serviço do número está fora do ar agora). `null` quando conectado ou sem registro de conexão.",
            "enum": [
              "logged_out",
              "temporary_ban",
              "disconnected",
              "stream_replaced",
              "client_outdated",
              "worker_unavailable",
              "unknown",
              null
            ]
          },
          "last_connection_event": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ConnectionEvent"
              },
              {
                "type": "null"
              }
            ],
            "description": "Último evento `instance.connection` do número (o mesmo de `GET /v1/events/{id}`), ou `null`."
          },
          "worker_alive": {
            "type": "boolean"
          },
          "lease_until": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "reservation_state": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "reserved",
              "occupied",
              null
            ]
          },
          "reservation_expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "LaunchLink": {
        "type": "object",
        "required": [
          "id",
          "slug",
          "url",
          "name",
          "cap",
          "active",
          "groups"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Endereço público (ex.: `https://flowzap.flowpost.com.br/g/lancamento`)."
          },
          "name": {
            "type": "string"
          },
          "cap": {
            "type": "integer"
          },
          "active": {
            "type": "boolean"
          },
          "auto_create": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "only_admins_send": {
                "type": "boolean"
              },
              "next_sequence": {
                "type": "integer"
              },
              "creating": {
                "type": "boolean"
              },
              "error": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "clicks": {
            "type": "integer"
          },
          "current_group_jid": {
            "type": [
              "string",
              "null"
            ],
            "description": "O grupo do próximo clique; null quando nenhum tem vaga."
          },
          "counted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Última leitura das pessoas no WhatsApp (no máximo a cada 2 minutos)."
          },
          "groups": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "group_jid": {
                  "$ref": "#/components/schemas/GroupJid"
                },
                "group_name": {
                  "type": "string"
                },
                "position": {
                  "type": "integer"
                },
                "participant_count": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "estimated_count": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Pessoas na última leitura mais os cliques desde então."
                },
                "clicks": {
                  "type": "integer"
                },
                "full": {
                  "type": "boolean"
                },
                "invite_ready": {
                  "type": "boolean"
                },
                "invite_error": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "missing": {
                  "type": "boolean",
                  "description": "O número não está mais no grupo."
                },
                "auto_created": {
                  "type": "boolean"
                }
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MediaKind": {
        "type": "string",
        "enum": [
          "image",
          "video",
          "audio",
          "document",
          "sticker"
        ]
      },
      "MediaObject": {
        "type": "object",
        "required": [
          "id",
          "kind",
          "mime_type",
          "file_name",
          "size_bytes",
          "sha256",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "$ref": "#/components/schemas/MediaKind"
          },
          "mime_type": {
            "type": "string"
          },
          "file_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "size_bytes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 16777216
          },
          "sha256": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "A mídia é apagada 48 horas após o envio."
          }
        },
        "additionalProperties": false
      },
      "MediaSource": {
        "type": "object",
        "description": "Exatamente uma origem: `id`, `base64` ou `url`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "ID de uma mídia enviada antes por `POST .../media`."
          },
          "base64": {
            "type": "string",
            "format": "byte",
            "minLength": 4,
            "maxLength": 955736,
            "description": "Arquivo em base64, até 700 KiB decodificados."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "pattern": "^https://",
            "description": "Endereço https público. O FlowZap baixa o arquivo (até 16 MiB, com proteção contra SSRF)."
          }
        },
        "additionalProperties": false,
        "oneOf": [
          {
            "required": [
              "id"
            ]
          },
          {
            "required": [
              "base64"
            ]
          },
          {
            "required": [
              "url"
            ]
          }
        ]
      },
      "Mention": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/E164"
          },
          {
            "type": "string",
            "pattern": "^\\d{5,20}@(?:s\\.whatsapp\\.net|lid)$",
            "description": "JID sem aparelho (telefone ou LID)."
          }
        ]
      },
      "MessageActionInput": {
        "type": "object",
        "required": [
          "chat"
        ],
        "properties": {
          "chat": {
            "$ref": "#/components/schemas/ChatJid"
          },
          "from_me": {
            "type": "boolean",
            "description": "Se omitido, é procurado no histórico do número."
          },
          "sender": {
            "$ref": "#/components/schemas/UserJid"
          }
        }
      },
      "MessageCommand": {
        "type": "object",
        "required": [
          "id",
          "state",
          "provider_message_id",
          "client_reference",
          "expires_at",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "queued",
              "dispatching",
              "provider_accepted",
              "delivered",
              "read",
              "failed",
              "unknown",
              "expired",
              "canceled"
            ]
          },
          "provider_message_id": {
            "type": "string",
            "description": "ID que a mensagem terá no WhatsApp."
          },
          "client_reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "MessageDestination": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "kind",
              "value"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "phone"
                ]
              },
              "value": {
                "$ref": "#/components/schemas/E164"
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": [
              "kind",
              "value"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "group"
                ]
              },
              "value": {
                "type": "string",
                "pattern": "^\\d{5,30}(?:-\\d{5,15})?@g\\.us$"
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": [
              "kind",
              "value"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "jid"
                ]
              },
              "value": {
                "type": "string",
                "pattern": "^\\d{5,20}@(?:s\\.whatsapp\\.net|lid)$",
                "description": "JID da conversa individual, sem aparelho: `<telefone>@s.whatsapp.net` ou um ID oculto `<dígitos>@lid`."
              }
            },
            "additionalProperties": false
          }
        ],
        "discriminator": {
          "propertyName": "kind"
        },
        "description": "Destino da mensagem:\n- `phone`: telefone E.164; o FlowZap confere no WhatsApp se o número existe antes de enviar.\n- `group`: JID do grupo (`…@g.us`).\n- `jid`: conversa individual pelo JID, enviada direto, sem consulta. Um LID (`…@lid`) é aceito como está: o FlowZap nunca deduz um telefone a partir dele.\n\nNuma resposta (`reply_to`) a uma mensagem recebida, o envio vai para a conversa da mensagem citada quando `to` é o mesmo contato por outro nome (LID ↔ telefone). Um LID e um telefone que não dá para comparar (o WhatsApp ainda não provou o par) são aceitos, e a resposta vai para a conversa citada."
      },
      "MessageDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/MessageCommand"
          },
          {
            "type": "object",
            "required": [
              "attempt",
              "receipts",
              "instance_id",
              "source",
              "actor_label"
            ],
            "properties": {
              "instance_id": {
                "type": "string",
                "format": "uuid",
                "description": "Número que enviou."
              },
              "source": {
                "type": "string",
                "enum": [
                  "api",
                  "console"
                ],
                "description": "`console`: enviado por uma pessoa no console; `api`: pela API (inclui integrações e automações)."
              },
              "actor_label": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Atendente: no console, o nome da pessoa; pela API, o `actor_label` enviado."
              },
              "attempt": {
                "type": [
                  "object",
                  "null"
                ],
                "required": [
                  "state",
                  "outcome_code",
                  "started_at",
                  "finished_at"
                ],
                "properties": {
                  "state": {
                    "type": "string",
                    "enum": [
                      "dispatching",
                      "provider_accepted",
                      "failed",
                      "unknown"
                    ]
                  },
                  "outcome_code": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Motivo do resultado. Em `failed` (nada saiu): `not_group_member`, `group_not_found`, `group_announce_only` (só administradores enviam; reações, edições e apagar não são conferidos), `not_group_admin`, `recipient_not_registered`, `recipient_invalid`, `send_prepare_failed` (o WhatsApp recusou antes de qualquer envio), `session_disconnected`, `media_unavailable`, `media_upload_failed`, `engine_capability_missing`, `message_type_not_supported`, `forward_media_expired`, `forward_media_unavailable`, `forward_media_too_large`, `forward_not_supported`, `forward_not_allowed`. O motor guarda as informações do grupo por até 60 segundos.\n\nEm `unknown` (`transport_ambiguous`): a mensagem pode ter saído. Nunca reenvie às cegas: consulte `GET /v1/messages?client_reference=…` ou espere os eventos."
                  },
                  "started_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "finished_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time"
                  }
                },
                "additionalProperties": false
              },
              "receipts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "kind",
                    "provider_timestamp",
                    "received_at"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "delivered",
                        "read"
                      ]
                    },
                    "provider_timestamp": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "received_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "additionalProperties": false
                },
                "description": "Recibos de mensagem direta. Os de grupo ficam em `group_receipts` e em `GET /v1/messages/{id}/receipts`."
              },
              "group_receipts": {
                "type": [
                  "object",
                  "null"
                ],
                "description": "Mensagem a um grupo: participantes que receberam e que leram (\"lida por `read` de `delivered`\"). `null` em mensagem direta ou antes da primeira confirmação.",
                "required": [
                  "delivered",
                  "read"
                ],
                "properties": {
                  "delivered": {
                    "type": "integer"
                  },
                  "read": {
                    "type": "integer"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        ]
      },
      "MessageEdit": {
        "type": "object",
        "required": [
          "text",
          "at"
        ],
        "properties": {
          "text": {
            "type": [
              "string",
              "null"
            ]
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "MessageRevoked": {
        "type": "object",
        "description": "A mensagem foi apagada para todos. O conteúdo original continua guardado e visível para os papéis que operam a organização e para as integrações dela com leitura de mensagens (`messages:read`, `engine:read`).",
        "required": [
          "at",
          "by"
        ],
        "properties": {
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "by": {
            "type": "string",
            "enum": [
              "contact",
              "team",
              "phone"
            ],
            "description": "contact: o contato (ou um participante do grupo); team: a equipe pelo FlowZap; phone: o celular do número."
          },
          "name": {
            "type": "string",
            "description": "Atendente (team) ou participante do grupo (contact), quando conhecido."
          },
          "admin": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Um administrador do grupo apagou a mensagem de outra pessoa; `name` é o administrador."
          }
        },
        "additionalProperties": false
      },
      "MessageTemplate": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "text",
              "image",
              "video",
              "document",
              "audio",
              "sticker",
              "location",
              "contact",
              "poll",
              "buttons",
              "list"
            ]
          }
        },
        "additionalProperties": true,
        "description": "Um corpo de envio (`SendMessage`) **sem** `to`, `expires_at`, `client_reference` e `reply_to`, que o FlowZap preenche por destinatário. Mídia precisa ser `id` ou `url` (base64 não é aceito)."
      },
      "MessageTemplateInput": {
        "type": "object",
        "required": [
          "name",
          "category",
          "message"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "description": "Único por escopo (a conta ou a área de trabalho), sem diferenciar maiúsculas."
          },
          "category": {
            "$ref": "#/components/schemas/TemplateCategory"
          },
          "message": {
            "$ref": "#/components/schemas/TemplateMessage"
          },
          "workspace_only": {
            "type": "boolean",
            "default": false,
            "description": "`true`: só os números desta área de trabalho veem o modelo. Uma chave presa a uma área de trabalho ou a um número sempre cria modelos da sua área."
          }
        },
        "additionalProperties": false
      },
      "MessageTemplateUpdate": {
        "type": "object",
        "required": [
          "name",
          "category",
          "message"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "category": {
            "$ref": "#/components/schemas/TemplateCategory"
          },
          "message": {
            "$ref": "#/components/schemas/TemplateMessage"
          }
        },
        "additionalProperties": false
      },
      "ModelosMessageTemplate": {
        "type": "object",
        "required": [
          "id",
          "name",
          "category",
          "workspace_id",
          "message",
          "variables",
          "uses_contact_data",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "$ref": "#/components/schemas/TemplateCategory"
          },
          "workspace_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "`null`: vale para todos os números da conta."
          },
          "message": {
            "$ref": "#/components/schemas/TemplateMessage"
          },
          "variables": {
            "type": "array",
            "description": "Variáveis livres do texto, na ordem de uso. Sem `fallback` (null), o envio precisa trazer o valor.",
            "items": {
              "type": "object",
              "required": [
                "name",
                "fallback"
              ],
              "properties": {
                "name": {
                  "type": "string"
                },
                "fallback": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "additionalProperties": false
            }
          },
          "uses_contact_data": {
            "type": "boolean",
            "description": "O texto usa `{{nome}}`, `{{primeiro_nome}}` ou `{{campo:…}}` (dados do CRM do número)."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "NewsletterJid": {
        "type": "string",
        "pattern": "^\\d{5,25}@newsletter$",
        "description": "JID de canal (ex.: `120363144038483540@newsletter`)."
      },
      "NewsletterMessage": {
        "type": "object",
        "required": [
          "id",
          "server_id",
          "type",
          "timestamp",
          "views",
          "reactions"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "server_id": {
            "type": "integer",
            "minimum": 1
          },
          "type": {
            "type": "string"
          },
          "timestamp": {
            "type": [
              "string",
              "null"
            ]
          },
          "views": {
            "type": "integer",
            "minimum": 0
          },
          "reactions": {
            "type": "object",
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            }
          },
          "text": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "NewsletterPostResult": {
        "type": "object",
        "required": [
          "jid",
          "id",
          "server_id",
          "timestamp"
        ],
        "properties": {
          "jid": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "server_id": {
            "type": "integer",
            "minimum": 1
          },
          "timestamp": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": false
      },
      "NewsletterSummary": {
        "type": "object",
        "required": [
          "jid",
          "name",
          "description",
          "invite_code",
          "invite_link",
          "subscriber_count",
          "verified",
          "state",
          "reaction_mode",
          "created_at",
          "picture",
          "role",
          "muted"
        ],
        "properties": {
          "jid": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "invite_code": {
            "type": "string"
          },
          "invite_link": {
            "type": [
              "string",
              "null"
            ]
          },
          "subscriber_count": {
            "type": "integer",
            "minimum": 0
          },
          "verified": {
            "type": "boolean"
          },
          "state": {
            "type": "string"
          },
          "reaction_mode": {
            "type": "string"
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "picture": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "id",
              "url"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "role": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "owner",
              "admin",
              "subscriber",
              "guest",
              null
            ]
          },
          "muted": {
            "type": [
              "boolean",
              "null"
            ]
          }
        },
        "additionalProperties": false
      },
      "NumberCapabilities": {
        "type": "object",
        "description": "O que a conexão do número pode fazer agora (`GET …/capabilities`).",
        "required": [
          "instance_id",
          "connected",
          "session_state",
          "disconnect_reason",
          "can_send",
          "can_send_reason",
          "new_conversations",
          "message_types",
          "text",
          "media",
          "groups",
          "lid",
          "quote",
          "react",
          "edit",
          "revoke",
          "forward",
          "mentions",
          "history_import",
          "on_demand_history",
          "receipts",
          "tickets",
          "calls",
          "recording",
          "unsupported",
          "limits",
          "engine"
        ],
        "properties": {
          "instance_id": {
            "type": "string",
            "format": "uuid"
          },
          "connected": {
            "type": "boolean",
            "description": "Número ativo, sessão conectada e serviço do número no ar."
          },
          "session_state": {
            "type": [
              "string",
              "null"
            ],
            "description": "Situação da sessão (mesmo vocabulário de `GET …/status`)."
          },
          "disconnect_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Mesmo campo de `GET …/status`."
          },
          "can_send": {
            "type": "boolean",
            "description": "`POST …/messages` seria aceito agora (fora limites de taxa e fila)."
          },
          "can_send_reason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "number_not_connected",
              "numbers_over_limit",
              "send_unavailable",
              null
            ],
            "description": "Por que não pode enviar; o mesmo `error.code` que o envio responderia."
          },
          "new_conversations": {
            "type": "string",
            "enum": [
              "allowed",
              "limited"
            ],
            "description": "`limited`: o último aviso do WhatsApp proíbe iniciar conversas novas (`GET …/limits`)."
          },
          "message_types": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Valores de `type` aceitos por `POST …/messages`, lidos do contrato de envio."
          },
          "text": {
            "type": "boolean"
          },
          "media": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "image",
                "video",
                "document",
                "audio",
                "sticker"
              ]
            },
            "description": "Tipos de mídia que podem ser enviados."
          },
          "groups": {
            "type": "object",
            "required": [
              "send",
              "manage"
            ],
            "properties": {
              "send": {
                "type": "boolean"
              },
              "manage": {
                "type": "boolean",
                "description": "Criar e administrar grupos (operações do número)."
              }
            },
            "additionalProperties": false
          },
          "lid": {
            "type": "object",
            "required": [
              "receive",
              "send"
            ],
            "properties": {
              "receive": {
                "type": "boolean",
                "description": "Conversas e remetentes chegam com LID (`<id>@lid`) quando o WhatsApp esconde o telefone."
              },
              "send": {
                "type": "boolean",
                "description": "`to: {kind: \"jid\", value: \"<id>@lid\"}` é aceito no envio."
              }
            },
            "additionalProperties": false
          },
          "quote": {
            "type": "boolean",
            "description": "Responder citando (`reply_to`)."
          },
          "react": {
            "type": "boolean"
          },
          "edit": {
            "type": "object",
            "required": [
              "supported",
              "window_minutes"
            ],
            "properties": {
              "supported": {
                "type": "boolean"
              },
              "window_minutes": {
                "type": "integer",
                "description": "Janela do WhatsApp para editar uma mensagem enviada."
              }
            },
            "additionalProperties": false
          },
          "revoke": {
            "type": "object",
            "required": [
              "supported",
              "window_hours",
              "group_admin_required_for_others"
            ],
            "properties": {
              "supported": {
                "type": "boolean"
              },
              "window_hours": {
                "type": "integer",
                "description": "Janela do WhatsApp para apagar para todos."
              },
              "group_admin_required_for_others": {
                "type": "boolean",
                "description": "Apagar mensagem de outra pessoa em grupo exige ser admin."
              }
            },
            "additionalProperties": false
          },
          "forward": {
            "type": "boolean",
            "description": "Encaminhamento nativo (`type: forward`)."
          },
          "mentions": {
            "type": "boolean"
          },
          "history_import": {
            "type": "boolean",
            "description": "Guardar o histórico que o celular manda ao conectar (`/settings/history`)."
          },
          "on_demand_history": {
            "type": "boolean",
            "description": "Pedir mais histórico de uma conversa (`POST …/chats/{jid}/history-sync`)."
          },
          "receipts": {
            "type": "object",
            "required": [
              "individual",
              "group"
            ],
            "properties": {
              "individual": {
                "type": "boolean"
              },
              "group": {
                "type": "boolean",
                "description": "Em grupo, contagem agregada em `GET /v1/messages/{id}/receipts`."
              }
            },
            "additionalProperties": false
          },
          "tickets": {
            "type": "boolean",
            "description": "Atendimentos (abertos/resolvidos, responsável)."
          },
          "calls": {
            "type": "object",
            "required": [
              "enabled",
              "mode",
              "audio_ws",
              "inbound",
              "outbound"
            ],
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "mode": {
                "type": "string",
                "enum": [
                  "off",
                  "test_callers",
                  "any_caller"
                ],
                "description": "`test_callers`: beta, só com os números de teste da conta; `any_caller`: módulo contratado."
              },
              "audio_ws": {
                "type": "boolean",
                "description": "Áudio da ligação por WebSocket (`audio: true` em `POST …/calls`)."
              },
              "inbound": {
                "type": "boolean"
              },
              "outbound": {
                "type": "boolean"
              }
            },
            "additionalProperties": false
          },
          "recording": {
            "type": "object",
            "required": [
              "enabled",
              "module",
              "retention_days"
            ],
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "Gravação de ligações ligada para o número."
              },
              "module": {
                "type": "boolean",
                "description": "Módulo \"Gravações no FlowZap\" contratado para o número."
              },
              "retention_days": {
                "type": "integer"
              }
            },
            "additionalProperties": false
          },
          "unsupported": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "delete_for_me",
                "contacts_create",
                "contacts_delete",
                "business_catalog",
                "business_profile_edit",
                "video_calls",
                "group_calls",
                "call_transfer"
              ]
            },
            "description": "O que o WhatsApp Web não oferece (rotas 501 ou inexistentes)."
          },
          "limits": {
            "type": "object",
            "required": [
              "send_rate_per_minute",
              "send_burst",
              "queue",
              "api_rate_per_minute"
            ],
            "properties": {
              "send_rate_per_minute": {
                "type": "integer",
                "description": "Envios por minuto por chave e número."
              },
              "send_burst": {
                "type": "integer"
              },
              "queue": {
                "type": "integer",
                "description": "Envios aguardando na fila do número (plano); acima, 429 `queue_full`."
              },
              "api_rate_per_minute": {
                "type": "integer",
                "description": "Pedidos por minuto da organização (todas as chaves)."
              }
            },
            "additionalProperties": false
          },
          "engine": {
            "type": "object",
            "required": [
              "kind",
              "version"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "whatsapp_web"
                ]
              },
              "version": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Versão do motor; `null` enquanto não é publicada."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "OperationEnvelope": {
        "type": "object",
        "description": "Uma operação em formato estável (`GET /v1/operations/{id}?envelope=1`).",
        "required": [
          "id",
          "kind",
          "state",
          "result",
          "error",
          "created_at",
          "updated_at",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "description": "Tipo da operação (ex.: `group.info`, `call.answer`)."
          },
          "state": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "succeeded",
              "failed",
              "unknown",
              "expired"
            ]
          },
          "result": {
            "description": "Resultado quando `succeeded` (o mesmo `data` da resposta sem envelope); senão `null`."
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "required": [
                  "code",
                  "retryable"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "`result_expired`, o código do WhatsApp (`failed`), `outcome_unknown` ou `engine_timeout`."
                  },
                  "retryable": {
                    "type": "boolean",
                    "description": "`true` só em `expired` (nada foi feito)."
                  }
                },
                "additionalProperties": false
              }
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "OperationPending": {
        "type": "object",
        "description": "A operação ainda não terminou. Consulte `GET /v1/operations/{id}` (cabeçalho `Location`).",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "operation_id",
              "state"
            ],
            "properties": {
              "operation_id": {
                "type": "string",
                "format": "uuid"
              },
              "state": {
                "type": "string",
                "enum": [
                  "queued",
                  "running"
                ]
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "OutboxEvent": {
        "type": "object",
        "required": [
          "event_id",
          "type",
          "workspace_id",
          "instance_id",
          "resource_id",
          "sequence",
          "occurred_at"
        ],
        "properties": {
          "event_id": {
            "type": "string",
            "format": "uuid"
          },
          "type": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "instance_id": {
            "type": "string",
            "format": "uuid"
          },
          "resource_id": {
            "type": "string",
            "format": "uuid",
            "description": "Mensagem enviada (`GET /v1/messages/{id}`), mensagem recebida (`GET .../inbound/{id}`) ou evento do motor (`GET /v1/events/{id}`), conforme o tipo."
          },
          "sequence": {
            "type": "integer",
            "minimum": 1,
            "description": "Crescente por número, sem lacunas."
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "OwnerInvitation": {
        "type": "object",
        "description": "Convite para ser dono de uma conta criada pela equipe FlowZap (página de aceite do console).",
        "required": [
          "organization_name",
          "email_masked",
          "existing_user",
          "expires_at"
        ],
        "properties": {
          "organization_name": {
            "type": "string",
            "description": "Nome da conta."
          },
          "email_masked": {
            "type": "string",
            "description": "E-mail convidado, mascarado (ex.: `an***@cliente.com.br`)."
          },
          "existing_user": {
            "type": "boolean",
            "description": "true quando o e-mail já tem cadastro confirmado: a pessoa entra no console e aceita com a sessão dela. Um cadastro ainda não confirmado conta como false (o aceite o aproveita)."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "PairingQr": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "status",
              "code",
              "expires_at"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "ready"
                ]
              },
              "code": {
                "type": "string",
                "description": "Conteúdo do QR code."
              },
              "expires_at": {
                "type": "string",
                "format": "date-time"
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": [
              "status",
              "session_state"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "linked"
                ]
              },
              "session_state": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": [
              "status",
              "session_state"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "pending"
                ]
              },
              "session_state": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "`needs_pairing` ou `revoked`: o celular desconectou o número; reconecte com `POST …/connect`."
              }
            },
            "additionalProperties": false
          }
        ],
        "discriminator": {
          "propertyName": "status"
        }
      },
      "PrivacyInput": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "setting",
              "value"
            ],
            "properties": {
              "setting": {
                "type": "string",
                "enum": [
                  "last"
                ]
              },
              "value": {
                "type": "string",
                "enum": [
                  "all",
                  "contacts",
                  "contact_blacklist",
                  "none"
                ]
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": [
              "setting",
              "value"
            ],
            "properties": {
              "setting": {
                "type": "string",
                "enum": [
                  "profile"
                ]
              },
              "value": {
                "type": "string",
                "enum": [
                  "all",
                  "contacts",
                  "contact_blacklist",
                  "none"
                ]
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": [
              "setting",
              "value"
            ],
            "properties": {
              "setting": {
                "type": "string",
                "enum": [
                  "status"
                ]
              },
              "value": {
                "type": "string",
                "enum": [
                  "all",
                  "contacts",
                  "contact_blacklist",
                  "none"
                ]
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": [
              "setting",
              "value"
            ],
            "properties": {
              "setting": {
                "type": "string",
                "enum": [
                  "groupadd"
                ]
              },
              "value": {
                "type": "string",
                "enum": [
                  "all",
                  "contacts",
                  "contact_blacklist",
                  "none"
                ]
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": [
              "setting",
              "value"
            ],
            "properties": {
              "setting": {
                "type": "string",
                "enum": [
                  "readreceipts"
                ]
              },
              "value": {
                "type": "string",
                "enum": [
                  "all",
                  "none"
                ]
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": [
              "setting",
              "value"
            ],
            "properties": {
              "setting": {
                "type": "string",
                "enum": [
                  "online"
                ]
              },
              "value": {
                "type": "string",
                "enum": [
                  "all",
                  "match_last_seen"
                ]
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": [
              "setting",
              "value"
            ],
            "properties": {
              "setting": {
                "type": "string",
                "enum": [
                  "calladd"
                ]
              },
              "value": {
                "type": "string",
                "enum": [
                  "all",
                  "known"
                ]
              }
            },
            "additionalProperties": false
          }
        ],
        "discriminator": {
          "propertyName": "setting"
        }
      },
      "ProxyInput": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "minLength": 8,
            "maxLength": 512,
            "description": "`http://`, `https://` ou `socks5://`, com usuário e senha opcionais. O host precisa ser público."
          }
        },
        "additionalProperties": false
      },
      "ProxyView": {
        "type": "object",
        "required": [
          "scheme",
          "host",
          "port",
          "credentials"
        ],
        "properties": {
          "scheme": {
            "type": "string",
            "enum": [
              "http",
              "https",
              "socks5"
            ]
          },
          "host": {
            "type": "string"
          },
          "port": {
            "type": "integer"
          },
          "credentials": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "***",
              null
            ]
          },
          "applies_on": {
            "type": "string",
            "enum": [
              "next_connection"
            ],
            "description": "Só na resposta do PUT: vale na próxima conexão (`POST /restart`)."
          }
        },
        "additionalProperties": false
      },
      "QueueView": {
        "type": "object",
        "required": [
          "counts",
          "items"
        ],
        "properties": {
          "counts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Total de envios por estado (ex.: `queued`, `read`)."
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "state",
                "client_reference",
                "created_at",
                "expires_at"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "queued",
                    "dispatching"
                  ]
                },
                "client_reference": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "expires_at": {
                  "type": "string",
                  "format": "date-time"
                }
              },
              "additionalProperties": false
            },
            "description": "Envios ainda na fila, do mais antigo ao mais novo. O conteúdo nunca é devolvido."
          }
        },
        "additionalProperties": false
      },
      "QuickReply": {
        "type": "object",
        "required": [
          "id",
          "shortcut",
          "message",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "shortcut": {
            "type": "string"
          },
          "message": {
            "type": "object",
            "additionalProperties": true
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "QuickReplyInput": {
        "type": "object",
        "required": [
          "shortcut",
          "message"
        ],
        "properties": {
          "shortcut": {
            "type": "string",
            "minLength": 1,
            "maxLength": 30,
            "pattern": "^[^\\s]+$"
          },
          "message": {
            "$ref": "#/components/schemas/MessageTemplate"
          }
        },
        "additionalProperties": false
      },
      "RecordingsAddon": {
        "type": "object",
        "description": "Gravações no FlowZap (R$ 29 por número/mês): quantidade contratada na assinatura, a que vale agora para o módulo (assinatura, licença ou cortesia), os números com ligações em vigor (o módulo grava ligações), o máximo do plano, o preço por número, a cota da conta em bytes (10 GB), a redução agendada e o aumento ainda por pagar (com o link).",
        "properties": {
          "recording_quantity": {
            "type": "integer"
          },
          "recording_quantity_in_force": {
            "type": "integer"
          },
          "call_quantity_in_force": {
            "type": "integer"
          },
          "max_quantity": {
            "type": [
              "integer",
              "null"
            ]
          },
          "recording_unit_amount_minor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Centavos."
          },
          "quota_bytes": {
            "type": "integer"
          },
          "scheduled_change": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "to_quantity": {
                "type": "integer"
              },
              "effective_at": {
                "type": "string",
                "format": "date-time"
              },
              "renewal_prepared": {
                "type": "boolean"
              }
            }
          },
          "pending_increase": {
            "type": [
              "object",
              "null"
            ],
            "description": "Aumento aguardando pagamento: `change_id`, `to_quantity`, `amount_minor`, `method`, `link`, `attempt_state`…"
          }
        }
      },
      "ReplyTo": {
        "type": "object",
        "description": "Responde (cita) uma mensagem do número, enviada ou recebida, procurada entre todas as mensagens guardadas do número. Em grupos, `participant` é quem escreveu a original.\n\nA citação é nativa: uma mensagem recebida aparece com o tipo original (imagem, vídeo, áudio, documento, figurinha com tipo de arquivo, legenda e miniatura; nunca o arquivo); uma mídia que este número enviou aparece pelo tipo, sem miniatura; uma mensagem de visualização única aparece só como texto. Em grupos, ao citar uma mensagem do próprio número, o participante citado é o próprio número.",
        "required": [
          "message_id"
        ],
        "properties": {
          "message_id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9._:-]{4,128}$",
            "description": "ID da mensagem no WhatsApp (ex.: `3EB0C767D0D1A2B3C4D5`)."
          },
          "participant": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/E164"
              },
              {
                "type": "string",
                "pattern": "^\\d{5,20}(?::\\d{1,3})?@(?:s\\.whatsapp\\.net|lid)$"
              }
            ]
          }
        },
        "additionalProperties": false
      },
      "ScheduledMessage": {
        "type": "object",
        "required": [
          "id",
          "state",
          "to",
          "scheduled_at",
          "message_type",
          "preview",
          "template_id",
          "template_name",
          "client_reference",
          "attempts",
          "error_code",
          "message_id",
          "message_state",
          "accepted_at",
          "canceled_at",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "scheduled",
              "accepted",
              "failed",
              "canceled"
            ],
            "description": "`scheduled` aguardando; `accepted` entregue à fila do número (acompanhe por `message_id`); `failed` não saiu (`error_code`); `canceled`."
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time"
          },
          "message_type": {
            "type": "string"
          },
          "preview": {
            "type": "string",
            "description": "Começo do texto (até 120 caracteres)."
          },
          "template_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "template_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "client_reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "attempts": {
            "type": "integer",
            "minimum": 0
          },
          "error_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Por que não saiu ou está sendo tentada de novo: `number_not_connected` (desconectado no horário e por 1 hora depois), `send_unavailable`, `numbers_over_limit`, `queue_full`, `operator_name_required`, `not_found`…"
          },
          "message_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "O envio (`GET /v1/messages/{id}`), depois de aceito."
          },
          "message_state": {
            "type": [
              "string",
              "null"
            ]
          },
          "accepted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "canceled_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "ScheduleMessageInput": {
        "type": "object",
        "required": [
          "to",
          "scheduled_at"
        ],
        "description": "Exatamente um de `message` ou `template_id`.",
        "properties": {
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time",
            "description": "De 1 minuto a 90 dias à frente, com fuso."
          },
          "message": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MessageTemplate"
              }
            ],
            "description": "Mensagem sem `to` e sem `expires_at`. Arquivo por `media.url`, ou `media.id` que dure até 1 hora depois do horário (uploads duram 48 h: senão 422 `media_expires_before_schedule`)."
          },
          "template_id": {
            "type": "string",
            "format": "uuid"
          },
          "variables": {
            "$ref": "#/components/schemas/TemplateValues"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "idempotency_key": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9_.:-]{1,128}$"
          }
        },
        "additionalProperties": false
      },
      "SendAudio": {
        "type": "object",
        "description": "Áudio: `audio/ogg`, `audio/mpeg`, `audio/mp4`, `audio/aac` ou `audio/amr`; `audio/webm` (gravação do navegador) só com `ptt: true`. Com `ptt: true` o servidor converte qualquer um desses para mensagem de voz (Ogg/Opus mono, 32 kbit/s) e calcula a duração e a onda exibidas no WhatsApp; a conversão de um mesmo upload é feita uma vez e reaproveitada nos envios seguintes. Limite da mensagem de voz: 30 minutos.",
        "required": [
          "to",
          "expires_at",
          "type",
          "media"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "reply_to": {
            "$ref": "#/components/schemas/ReplyTo"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Mention"
            },
            "minItems": 1,
            "maxItems": 50,
            "description": "Pessoas mencionadas (@): telefone E.164 ou JID (telefone ou LID). O texto deve conter `@<número>` ou `@<dígitos do LID>` de cada uma para o WhatsApp destacar."
          },
          "type": {
            "type": "string",
            "enum": [
              "audio"
            ]
          },
          "media": {
            "$ref": "#/components/schemas/MediaSource"
          },
          "mime_type": {
            "type": "string",
            "maxLength": 100,
            "pattern": "^[a-z0-9][a-z0-9.+-]*/[a-z0-9][a-z0-9.+-]*$",
            "description": "Tipo MIME (ex.: `image/jpeg`)."
          },
          "ptt": {
            "type": "boolean",
            "description": "true envia como mensagem de voz (gravada na hora, com onda e duração). O servidor converte o áudio automaticamente; não é preciso mandar Ogg/Opus. Áudio ilegível responde 422 `audio_unreadable`."
          }
        },
        "additionalProperties": false
      },
      "SendButtons": {
        "type": "object",
        "required": [
          "to",
          "expires_at",
          "type",
          "buttons"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "reply_to": {
            "$ref": "#/components/schemas/ReplyTo"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Mention"
            },
            "minItems": 1,
            "maxItems": 50,
            "description": "Pessoas mencionadas (@): telefone E.164 ou JID (telefone ou LID). O texto deve conter `@<número>` ou `@<dígitos do LID>` de cada uma para o WhatsApp destacar."
          },
          "type": {
            "type": "string",
            "enum": [
              "buttons"
            ]
          },
          "buttons": {
            "type": "object",
            "required": [
              "text",
              "items"
            ],
            "properties": {
              "text": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1024
              },
              "footer": {
                "type": "string",
                "minLength": 1,
                "maxLength": 60
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "title"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100
                    },
                    "title": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 20
                    }
                  },
                  "additionalProperties": false
                },
                "minItems": 1,
                "maxItems": 3
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "SendCarousel": {
        "type": "object",
        "description": "Beta. Carrossel de 2 a 10 cartões, cada um com foto ou vídeo já enviado (`POST …/media`; todos do mesmo tipo), título opcional, texto e 1 ou 2 botões (`quick_reply` e/ou `url`), com a mesma sequência de botões em todos os cartões. Vai como mensagem interativa pelo protocolo não oficial: o WhatsApp pode aceitar o envio e alguns aparelhos ou contas não exibirem os cartões; teste com um número seu. A resposta da pessoa a um botão chega como mensagem `buttons_reply` com o texto do botão.",
        "required": [
          "to",
          "expires_at",
          "type",
          "carousel"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "reply_to": {
            "$ref": "#/components/schemas/ReplyTo"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/E164"
            },
            "minItems": 1,
            "maxItems": 50
          },
          "type": {
            "type": "string",
            "enum": [
              "carousel"
            ]
          },
          "carousel": {
            "type": "object",
            "required": [
              "cards"
            ],
            "properties": {
              "text": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1024,
                "description": "Texto acima dos cartões."
              },
              "cards": {
                "type": "array",
                "minItems": 2,
                "maxItems": 10,
                "items": {
                  "type": "object",
                  "required": [
                    "media",
                    "body",
                    "buttons"
                  ],
                  "properties": {
                    "media": {
                      "type": "object",
                      "required": [
                        "id"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Mídia `image` ou `video` enviada antes (`POST …/media`)."
                        }
                      },
                      "additionalProperties": false
                    },
                    "title": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 60
                    },
                    "body": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 160
                    },
                    "buttons": {
                      "type": "array",
                      "minItems": 1,
                      "maxItems": 2,
                      "items": {
                        "oneOf": [
                          {
                            "type": "object",
                            "required": [
                              "type",
                              "id",
                              "text"
                            ],
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "quick_reply"
                                ]
                              },
                              "id": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 100,
                                "description": "Único no carrossel (senão 400 `invalid_input`)."
                              },
                              "text": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 25
                              }
                            },
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "required": [
                              "type",
                              "text",
                              "url"
                            ],
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "url"
                                ]
                              },
                              "text": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 25
                              },
                              "url": {
                                "type": "string",
                                "format": "uri",
                                "maxLength": 2048,
                                "description": "`http` ou `https`."
                              }
                            },
                            "additionalProperties": false
                          }
                        ]
                      }
                    }
                  },
                  "additionalProperties": false
                }
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "SendContact": {
        "type": "object",
        "required": [
          "to",
          "expires_at",
          "type",
          "contacts"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "reply_to": {
            "$ref": "#/components/schemas/ReplyTo"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Mention"
            },
            "minItems": 1,
            "maxItems": 50,
            "description": "Pessoas mencionadas (@): telefone E.164 ou JID (telefone ou LID). O texto deve conter `@<número>` ou `@<dígitos do LID>` de cada uma para o WhatsApp destacar."
          },
          "type": {
            "type": "string",
            "enum": [
              "contact"
            ]
          },
          "contacts": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "phones"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160
                },
                "phones": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/E164"
                  },
                  "minItems": 1,
                  "maxItems": 5
                },
                "organization": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160
                }
              },
              "additionalProperties": false
            },
            "minItems": 1,
            "maxItems": 10
          }
        },
        "additionalProperties": false
      },
      "SendDelay": {
        "type": "object",
        "description": "Pausa aleatória entre dois envios da fila do número.",
        "required": [
          "min_ms",
          "max_ms"
        ],
        "properties": {
          "min_ms": {
            "type": "integer",
            "minimum": 0,
            "maximum": 600000
          },
          "max_ms": {
            "type": "integer",
            "minimum": 0,
            "maximum": 600000,
            "description": "Precisa ser maior ou igual a `min_ms`."
          }
        },
        "additionalProperties": false
      },
      "SendDocument": {
        "type": "object",
        "description": "Documento de qualquer tipo bem formado, exceto HTML e XML.",
        "required": [
          "to",
          "expires_at",
          "type",
          "media"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "reply_to": {
            "$ref": "#/components/schemas/ReplyTo"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Mention"
            },
            "minItems": 1,
            "maxItems": 50,
            "description": "Pessoas mencionadas (@): telefone E.164 ou JID (telefone ou LID). O texto deve conter `@<número>` ou `@<dígitos do LID>` de cada uma para o WhatsApp destacar."
          },
          "type": {
            "type": "string",
            "enum": [
              "document"
            ]
          },
          "media": {
            "$ref": "#/components/schemas/MediaSource"
          },
          "mime_type": {
            "type": "string",
            "maxLength": 100,
            "pattern": "^[a-z0-9][a-z0-9.+-]*/[a-z0-9][a-z0-9.+-]*$",
            "description": "Tipo MIME (ex.: `image/jpeg`)."
          },
          "caption": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024
          },
          "file_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "pattern": "^[^/\\\\\\p{Cc}]+$"
          }
        },
        "additionalProperties": false
      },
      "SendEdit": {
        "type": "object",
        "description": "Edita o texto de uma mensagem **enviada por este número** em até 15 minutos (senão 422 `edit_window_expired`). Mensagem de outra pessoa: 422 `target_not_editable`.",
        "required": [
          "to",
          "expires_at",
          "type",
          "edit"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "type": {
            "type": "string",
            "enum": [
              "edit"
            ]
          },
          "edit": {
            "type": "object",
            "required": [
              "message_id",
              "text"
            ],
            "properties": {
              "message_id": {
                "type": "string",
                "pattern": "^[A-Za-z0-9._:-]{4,128}$",
                "description": "ID da mensagem no WhatsApp (ex.: `3EB0C767D0D1A2B3C4D5`)."
              },
              "text": {
                "type": "string",
                "minLength": 1,
                "maxLength": 4096
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "SendForward": {
        "type": "object",
        "description": "Encaminha uma mensagem que este número enviou ou recebeu (mesmo número), marcada \"Encaminhada\" no WhatsApp. A contagem de encaminhamentos é a anterior + 1 (máximo 127).\n- Envio do próprio número: o conteúdo é copiado (texto, mídia enquanto o upload existir — 48 horas —, localização, contato).\n- Mensagem recebida: texto, imagem, vídeo, áudio, documento, figurinha, localização e contato. A mídia é baixada do WhatsApp e enviada de novo pelo motor na hora do envio.\n\nNão é possível encaminhar reação, edição, enquete e outros tipos (422 `forward_not_supported`) nem visualização única (422 `forward_not_allowed`). Upload já apagado: 422 `forward_media_expired`; arquivo acima de 16 MiB: 422 `forward_media_too_large`. Falhas na hora do envio terminam `failed` com `forward_media_expired` (o WhatsApp não tem mais o arquivo), `forward_media_unavailable`, `forward_media_too_large`, `forward_not_supported` ou `forward_not_allowed`; nada foi enviado nesses casos.",
        "required": [
          "to",
          "expires_at",
          "type",
          "forward"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "type": {
            "type": "string",
            "enum": [
              "forward"
            ]
          },
          "forward": {
            "type": "object",
            "required": [
              "message_id"
            ],
            "properties": {
              "message_id": {
                "type": "string",
                "pattern": "^[A-Za-z0-9._:-]{4,128}$",
                "description": "ID no WhatsApp da mensagem a encaminhar."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "SendImage": {
        "type": "object",
        "description": "Imagem: `image/jpeg`, `image/png` ou `image/webp`.",
        "required": [
          "to",
          "expires_at",
          "type",
          "media"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "reply_to": {
            "$ref": "#/components/schemas/ReplyTo"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Mention"
            },
            "minItems": 1,
            "maxItems": 50,
            "description": "Pessoas mencionadas (@): telefone E.164 ou JID (telefone ou LID). O texto deve conter `@<número>` ou `@<dígitos do LID>` de cada uma para o WhatsApp destacar."
          },
          "type": {
            "type": "string",
            "enum": [
              "image"
            ]
          },
          "media": {
            "$ref": "#/components/schemas/MediaSource"
          },
          "mime_type": {
            "type": "string",
            "maxLength": 100,
            "pattern": "^[a-z0-9][a-z0-9.+-]*/[a-z0-9][a-z0-9.+-]*$",
            "description": "Tipo MIME (ex.: `image/jpeg`)."
          },
          "caption": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024
          }
        },
        "additionalProperties": false
      },
      "SendList": {
        "type": "object",
        "required": [
          "to",
          "expires_at",
          "type",
          "list"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "reply_to": {
            "$ref": "#/components/schemas/ReplyTo"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Mention"
            },
            "minItems": 1,
            "maxItems": 50,
            "description": "Pessoas mencionadas (@): telefone E.164 ou JID (telefone ou LID). O texto deve conter `@<número>` ou `@<dígitos do LID>` de cada uma para o WhatsApp destacar."
          },
          "type": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "list": {
            "type": "object",
            "required": [
              "text",
              "button_text",
              "sections"
            ],
            "properties": {
              "text": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1024
              },
              "button_text": {
                "type": "string",
                "minLength": 1,
                "maxLength": 20
              },
              "footer": {
                "type": "string",
                "minLength": 1,
                "maxLength": 60
              },
              "sections": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "title",
                    "rows"
                  ],
                  "properties": {
                    "title": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 24
                    },
                    "rows": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "title"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 100
                          },
                          "title": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 24
                          },
                          "description": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 72
                          }
                        },
                        "additionalProperties": false
                      },
                      "minItems": 1,
                      "maxItems": 10
                    }
                  },
                  "additionalProperties": false
                },
                "minItems": 1,
                "maxItems": 10
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "SendLocation": {
        "type": "object",
        "required": [
          "to",
          "expires_at",
          "type",
          "location"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "reply_to": {
            "$ref": "#/components/schemas/ReplyTo"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Mention"
            },
            "minItems": 1,
            "maxItems": 50,
            "description": "Pessoas mencionadas (@): telefone E.164 ou JID (telefone ou LID). O texto deve conter `@<número>` ou `@<dígitos do LID>` de cada uma para o WhatsApp destacar."
          },
          "type": {
            "type": "string",
            "enum": [
              "location"
            ]
          },
          "location": {
            "type": "object",
            "required": [
              "latitude",
              "longitude"
            ],
            "properties": {
              "latitude": {
                "type": "number",
                "minimum": -90,
                "maximum": 90
              },
              "longitude": {
                "type": "number",
                "minimum": -180,
                "maximum": 180
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 256
              },
              "address": {
                "type": "string",
                "minLength": 1,
                "maxLength": 512
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "SendMessage": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/SendText"
          },
          {
            "$ref": "#/components/schemas/SendImage"
          },
          {
            "$ref": "#/components/schemas/SendVideo"
          },
          {
            "$ref": "#/components/schemas/SendDocument"
          },
          {
            "$ref": "#/components/schemas/SendAudio"
          },
          {
            "$ref": "#/components/schemas/SendSticker"
          },
          {
            "$ref": "#/components/schemas/SendLocation"
          },
          {
            "$ref": "#/components/schemas/SendContact"
          },
          {
            "$ref": "#/components/schemas/SendReaction"
          },
          {
            "$ref": "#/components/schemas/SendPoll"
          },
          {
            "$ref": "#/components/schemas/SendEdit"
          },
          {
            "$ref": "#/components/schemas/SendRevoke"
          },
          {
            "$ref": "#/components/schemas/SendForward"
          },
          {
            "$ref": "#/components/schemas/SendButtons"
          },
          {
            "$ref": "#/components/schemas/SendList"
          },
          {
            "$ref": "#/components/schemas/SendCarousel"
          },
          {
            "$ref": "#/components/schemas/SendStatus"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "text": "#/SendText",
            "image": "#/SendImage",
            "video": "#/SendVideo",
            "document": "#/SendDocument",
            "audio": "#/SendAudio",
            "sticker": "#/SendSticker",
            "location": "#/SendLocation",
            "contact": "#/SendContact",
            "reaction": "#/SendReaction",
            "poll": "#/SendPoll",
            "edit": "#/SendEdit",
            "revoke": "#/SendRevoke",
            "forward": "#/SendForward",
            "buttons": "#/SendButtons",
            "list": "#/SendList",
            "carousel": "#/SendCarousel",
            "status": "#/SendStatus"
          }
        },
        "description": "Corpo de envio. `type` escolhe a variante; campos a mais são recusados (400 `invalid_input`).\n\nQualquer variante aceita também `actor_label` (opcional, 1 a 80 caracteres, espaços nas pontas removidos): o nome do atendente externo que enviou. Fica gravado com o envio e volta em `GET /v1/messages/{id}`; não é conteúdo da mensagem e não entra na comparação de idempotência (repetir com a mesma `Idempotency-Key` mantém o rótulo do primeiro pedido). Inválido: 400 `invalid_input`."
      },
      "SendPoll": {
        "type": "object",
        "required": [
          "to",
          "expires_at",
          "type",
          "poll"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "reply_to": {
            "$ref": "#/components/schemas/ReplyTo"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Mention"
            },
            "minItems": 1,
            "maxItems": 50,
            "description": "Pessoas mencionadas (@): telefone E.164 ou JID (telefone ou LID). O texto deve conter `@<número>` ou `@<dígitos do LID>` de cada uma para o WhatsApp destacar."
          },
          "type": {
            "type": "string",
            "enum": [
              "poll"
            ]
          },
          "poll": {
            "type": "object",
            "required": [
              "name",
              "options",
              "selectable_count"
            ],
            "properties": {
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255
              },
              "options": {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 100
                },
                "minItems": 2,
                "maxItems": 12,
                "uniqueItems": true
              },
              "selectable_count": {
                "type": "integer",
                "minimum": 1,
                "description": "Quantas opções cada pessoa pode marcar; no máximo o total de opções."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "SendReaction": {
        "type": "object",
        "required": [
          "to",
          "expires_at",
          "type",
          "reaction"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "type": {
            "type": "string",
            "enum": [
              "reaction"
            ]
          },
          "reaction": {
            "type": "object",
            "required": [
              "message_id",
              "emoji"
            ],
            "properties": {
              "message_id": {
                "type": "string",
                "pattern": "^[A-Za-z0-9._:-]{4,128}$",
                "description": "ID da mensagem no WhatsApp (ex.: `3EB0C767D0D1A2B3C4D5`)."
              },
              "emoji": {
                "type": "string",
                "maxLength": 32,
                "description": "Emoji vazio remove a reação."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "SendRevoke": {
        "type": "object",
        "description": "Apaga para todos em até 48 horas (senão 422 `revoke_window_expired`).\n- Mensagem enviada por este número: sempre.\n- Mensagem de outro participante num grupo: só com o número administrador. Antes de aceitar, a API consulta o grupo pelo motor (espera até ~8 s): sem admin, 422 `not_group_admin`; fora do grupo, 422 `not_group_member`. Se a resposta atrasar, o pedido entra na fila e o motor confere de novo antes de enviar; aí o envio termina `failed` com o mesmo código.\n- Mensagem de um contato numa conversa individual: 422 `target_not_revocable`.\n\n\"Apagar só para mim\" não é suportado: não existe rota para isso (é uma ação local do celular).",
        "required": [
          "to",
          "expires_at",
          "type",
          "revoke"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "type": {
            "type": "string",
            "enum": [
              "revoke"
            ]
          },
          "revoke": {
            "type": "object",
            "required": [
              "message_id"
            ],
            "properties": {
              "message_id": {
                "type": "string",
                "pattern": "^[A-Za-z0-9._:-]{4,128}$",
                "description": "ID da mensagem no WhatsApp (ex.: `3EB0C767D0D1A2B3C4D5`)."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "SendStatus": {
        "type": "object",
        "description": "Publica um status (story).",
        "required": [
          "expires_at",
          "type",
          "status"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination",
            "description": "Aceito e ignorado: status vai para `status@broadcast`."
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data e hora ISO 8601 com fuso (ex.: `2026-10-01T18:00:00Z`)."
          },
          "type": {
            "type": "string",
            "enum": [
              "status"
            ]
          },
          "status": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "type",
                  "text"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "text"
                    ]
                  },
                  "text": {
                    "type": "object",
                    "required": [
                      "body"
                    ],
                    "properties": {
                      "body": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 700
                      }
                    },
                    "additionalProperties": false
                  },
                  "background_color": {
                    "type": "string",
                    "pattern": "^#[0-9a-fA-F]{6}$",
                    "description": "Cor de fundo `#RRGGBB` (padrão `#075E54`); o texto sai branco."
                  },
                  "font": {
                    "$ref": "#/components/schemas/StatusFont"
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "object",
                "required": [
                  "type",
                  "media"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "image",
                      "video",
                      "audio"
                    ]
                  },
                  "media": {
                    "$ref": "#/components/schemas/MediaSource"
                  },
                  "mime_type": {
                    "type": "string",
                    "maxLength": 100,
                    "pattern": "^[a-z0-9][a-z0-9.+-]*/[a-z0-9][a-z0-9.+-]*$",
                    "description": "Tipo MIME (ex.: `image/jpeg`)."
                  },
                  "caption": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1024
                  }
                },
                "additionalProperties": false
              }
            ]
          }
        },
        "additionalProperties": false
      },
      "SendSticker": {
        "type": "object",
        "description": "Figurinha `image/webp`.",
        "required": [
          "to",
          "expires_at",
          "type",
          "media"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "reply_to": {
            "$ref": "#/components/schemas/ReplyTo"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Mention"
            },
            "minItems": 1,
            "maxItems": 50,
            "description": "Pessoas mencionadas (@): telefone E.164 ou JID (telefone ou LID). O texto deve conter `@<número>` ou `@<dígitos do LID>` de cada uma para o WhatsApp destacar."
          },
          "type": {
            "type": "string",
            "enum": [
              "sticker"
            ]
          },
          "media": {
            "$ref": "#/components/schemas/MediaSource"
          },
          "mime_type": {
            "type": "string",
            "maxLength": 100,
            "pattern": "^[a-z0-9][a-z0-9.+-]*/[a-z0-9][a-z0-9.+-]*$",
            "description": "Tipo MIME (ex.: `image/jpeg`)."
          }
        },
        "additionalProperties": false
      },
      "SendTemplateInput": {
        "type": "object",
        "required": [
          "to",
          "template_id"
        ],
        "properties": {
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "template_id": {
            "type": "string",
            "format": "uuid"
          },
          "variables": {
            "$ref": "#/components/schemas/TemplateValues"
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time",
            "description": "Agenda em vez de enviar agora: de 1 minuto a 90 dias à frente, com fuso (ex.: `2026-10-20T09:00:00-03:00`). Responde 201 com a mensagem agendada."
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (pedido, cobrança), devolvida no envio e nos eventos."
          },
          "idempotency_key": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9_.:-]{1,128}$",
            "description": "Alternativa ao cabeçalho `Idempotency-Key` (se vierem os dois, precisam ser iguais)."
          }
        },
        "additionalProperties": false
      },
      "SendText": {
        "type": "object",
        "required": [
          "to",
          "expires_at",
          "type",
          "text"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "reply_to": {
            "$ref": "#/components/schemas/ReplyTo"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Mention"
            },
            "minItems": 1,
            "maxItems": 50,
            "description": "Pessoas mencionadas (@): telefone E.164 ou JID (telefone ou LID). O texto deve conter `@<número>` ou `@<dígitos do LID>` de cada uma para o WhatsApp destacar."
          },
          "type": {
            "type": "string",
            "enum": [
              "text"
            ]
          },
          "text": {
            "type": "object",
            "required": [
              "body"
            ],
            "properties": {
              "body": {
                "type": "string",
                "minLength": 1,
                "maxLength": 4096
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "SendVideo": {
        "type": "object",
        "description": "Vídeo: `video/mp4` ou `video/3gpp`.",
        "required": [
          "to",
          "expires_at",
          "type",
          "media"
        ],
        "properties": {
          "actor_label": {
            "$ref": "#/components/schemas/ActorLabel"
          },
          "to": {
            "$ref": "#/components/schemas/MessageDestination"
          },
          "client_reference": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Sua referência (ex.: número do pedido). Volta nas consultas."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Prazo para o envio acontecer: no futuro e no máximo 7 dias à frente (senão 400 `invalid_expiry`). Depois dele, a mensagem vira `expired` e não sai."
          },
          "reply_to": {
            "$ref": "#/components/schemas/ReplyTo"
          },
          "mentions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Mention"
            },
            "minItems": 1,
            "maxItems": 50,
            "description": "Pessoas mencionadas (@): telefone E.164 ou JID (telefone ou LID). O texto deve conter `@<número>` ou `@<dígitos do LID>` de cada uma para o WhatsApp destacar."
          },
          "type": {
            "type": "string",
            "enum": [
              "video"
            ]
          },
          "media": {
            "$ref": "#/components/schemas/MediaSource"
          },
          "mime_type": {
            "type": "string",
            "maxLength": 100,
            "pattern": "^[a-z0-9][a-z0-9.+-]*/[a-z0-9][a-z0-9.+-]*$",
            "description": "Tipo MIME (ex.: `image/jpeg`)."
          },
          "caption": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024
          }
        },
        "additionalProperties": false
      },
      "Signature": {
        "type": "object",
        "description": "Assinatura do atendente nas respostas enviadas pelo console.",
        "required": [
          "enabled"
        ],
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "`true`: o cliente vê `*Nome do atendente:*` na primeira linha."
          }
        },
        "additionalProperties": false
      },
      "SlotReservation": {
        "type": "object",
        "required": [
          "id",
          "instance_id",
          "state",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "instance_id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "reserved",
              "occupied"
            ]
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "StatusFont": {
        "type": "string",
        "description": "Fonte do texto no Status (nomes do WhatsApp). Padrão `system`.",
        "enum": [
          "system",
          "system_text",
          "fb_script",
          "system_bold",
          "morningbreeze_regular",
          "calistoga_regular",
          "exo2_extrabold",
          "courierprime_bold"
        ]
      },
      "StreamToken": {
        "type": "object",
        "required": [
          "token",
          "expires_at",
          "url"
        ],
        "properties": {
          "token": {
            "type": "string",
            "pattern": "^fzs1\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]{43}$",
            "description": "Token do fluxo (5 minutos). Vale só em `GET /v1/events/stream?token=…`; não é chave de API."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "url": {
            "type": "string",
            "description": "`/v1/events/stream?token=<token>`; acrescente os outros parâmetros (`instance_id`, `types`, `cursor`)."
          }
        },
        "additionalProperties": false
      },
      "TeamInvitation": {
        "type": "object",
        "required": [
          "id",
          "email",
          "role",
          "workspace_id",
          "status",
          "invited_by",
          "expires_at",
          "accepted_at",
          "revoked_at",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "email": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "admin",
              "developer",
              "operator",
              "billing",
              "viewer"
            ]
          },
          "workspace_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "accepted",
              "revoked",
              "expired"
            ]
          },
          "invited_by": {
            "type": "string",
            "format": "uuid",
            "description": "Pessoa que convidou (no convite por API, quem criou a chave)."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "accepted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "revoked_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "TeamInvitationCreated": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "id",
              "email",
              "role",
              "workspace_id"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "email": {
                "type": "string"
              },
              "role": {
                "type": "string",
                "enum": [
                  "admin",
                  "developer",
                  "operator",
                  "billing",
                  "viewer"
                ]
              },
              "workspace_id": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid"
              }
            }
          }
        }
      },
      "TeamMember": {
        "type": "object",
        "description": "Um acesso de uma pessoa à organização (inteira) ou a uma área de trabalho.",
        "required": [
          "id",
          "user_id",
          "email",
          "role",
          "workspace_id",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "ID do acesso (usado em `DELETE /v1/team/members/{membershipId}`)."
          },
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "email": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "developer",
              "operator",
              "billing",
              "viewer"
            ]
          },
          "workspace_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "`null`: acesso à organização inteira."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "TemplateCategory": {
        "type": "string",
        "enum": [
          "aviso",
          "cobranca",
          "lembrete",
          "outro"
        ],
        "description": "Tipo do modelo: `aviso`, `cobranca`, `lembrete` ou `outro`."
      },
      "TemplateMessage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/MessageTemplate"
          }
        ],
        "description": "Corpo do modelo: uma mensagem sem destinatário (como a de uma campanha). Arquivo só por link `https` (`media.url`): o modelo vale para a conta toda, e arquivos enviados pelo upload são de um número e duram 48 h.\n\nO texto (`text.body`, `caption`, `buttons.text` ou `list.text`) aceita:\n- dados do CRM do número: `{{nome}}`, `{{primeiro_nome}}`, `{{campo:<chave>}}`;\n- variáveis livres, preenchidas no envio: `{{var:valor}}`, `{{var:link}}`, `{{var:data}}`… (nome com letras minúsculas, números e `_`, até 40).\n\nQualquer marcador aceita um texto alternativo depois de `|`: `{{primeiro_nome|cliente}}`, `{{var:desconto|10%}}`; `{{var:obs|}}` é opcional e some quando não vier. Marcador desconhecido ou mal fechado: 422 `invalid_placeholder`."
      },
      "TemplateValues": {
        "type": "object",
        "maxProperties": 30,
        "propertyNames": {
          "pattern": "^[a-z0-9_]{1,40}$"
        },
        "additionalProperties": {
          "type": "string",
          "maxLength": 1000
        },
        "description": "Valores das variáveis `{{var:…}}`. `nome`, quando vem, é o nome da pessoa em `{{nome}}` e `{{primeiro_nome}}` (no lugar do nome do CRM). Faltou uma variável sem alternativo: 422 `missing_variables` com `missing` (os nomes)."
      },
      "Ticket": {
        "type": "object",
        "required": [
          "id",
          "contact",
          "lead",
          "status",
          "assigned_user_id",
          "opened_at",
          "resolved_at",
          "resolved_by_user_id",
          "reopen_count",
          "csat",
          "pending",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "contact": {
            "type": "string",
            "description": "Telefone `+55…` ou, sem telefone conhecido, contato `…@lid`. Num grupo, o nome dado ao abrir o atendimento (sem nome, `Grupo`); o JID do grupo não aparece."
          },
          "lead": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "id",
              "name",
              "stage_id"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "stage_id": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "additionalProperties": false,
            "description": "O contato no funil, quando existe."
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "resolved"
            ]
          },
          "assigned_user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "opened_at": {
            "type": "string"
          },
          "resolved_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "resolved_by_user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "reopen_count": {
            "type": "integer"
          },
          "csat": {
            "type": "object",
            "required": [
              "status",
              "score",
              "sent_at",
              "answered_at"
            ],
            "properties": {
              "status": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "pending",
                  "sent",
                  "answered",
                  "expired",
                  "skipped",
                  null
                ]
              },
              "score": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 1,
                "maximum": 5
              },
              "sent_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "answered_at": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "additionalProperties": false,
            "description": "Pesquisa de satisfação depois de resolver: `pending` (na fila), `sent`, `answered`, `expired` (sem resposta em 24 h), `skipped`."
          },
          "pending": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "level",
              "note",
              "by_user_id",
              "by_name",
              "at"
            ],
            "properties": {
              "level": {
                "type": "string",
                "enum": [
                  "urgent",
                  "medium",
                  "low"
                ],
                "description": "`urgent` (urgente), `medium` (média urgência) ou `low` (baixa urgência)."
              },
              "note": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 280
              },
              "by_user_id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Quem marcou (pela API, a pessoa que criou a chave); `null` sem pessoa."
              },
              "by_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Nome (ou e-mail) de quem marcou."
              },
              "at": {
                "type": "string"
              }
            },
            "additionalProperties": false,
            "description": "Pendência do atendimento aberto; `null` sem pendência. Com pendência, resolver responde 409 `ticket_pending`."
          },
          "updated_at": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "TicketAssigneeInput": {
        "type": "object",
        "required": [
          "user_id"
        ],
        "properties": {
          "user_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Pessoa da equipe; `null` tira o responsável."
          },
          "reason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 280,
            "description": "Motivo da mudança, guardado no histórico do atendimento."
          },
          "actor_label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Nome do atendente no seu sistema, guardado no histórico como enviado (declarado, não verificado)."
          }
        },
        "additionalProperties": false
      },
      "TicketBulkInput": {
        "type": "object",
        "required": [
          "action",
          "contacts"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "resolve",
              "reopen",
              "pending_set",
              "pending_clear",
              "assign"
            ]
          },
          "contacts": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "oneOf": [
                {
                  "type": "string",
                  "maxLength": 64,
                  "description": "Id do atendimento, telefone E.164, contato `…@lid` ou grupo `group:<jid>`."
                },
                {
                  "type": "object",
                  "required": [
                    "contact",
                    "name"
                  ],
                  "properties": {
                    "contact": {
                      "type": "string",
                      "maxLength": 64
                    },
                    "name": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 120,
                      "description": "Nome do grupo, guardado se o atendimento for aberto agora."
                    }
                  },
                  "additionalProperties": false
                }
              ]
            }
          },
          "level": {
            "type": "string",
            "enum": [
              "urgent",
              "medium",
              "low"
            ],
            "description": "Obrigatório em `pending_set`."
          },
          "note": {
            "type": "string",
            "minLength": 1,
            "maxLength": 280,
            "description": "Observação da pendência (`pending_set`)."
          },
          "user_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Obrigatório em `assign`; `null` tira o responsável."
          },
          "send_csat": {
            "type": "boolean",
            "description": "`resolve`: `false` não envia a pesquisa de satisfação. Sem o campo, segue a configuração do número."
          },
          "reason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 280,
            "description": "Motivo da mudança, guardado no histórico do atendimento."
          },
          "actor_label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Nome do atendente no seu sistema, guardado no histórico como enviado (declarado, não verificado)."
          }
        },
        "additionalProperties": false
      },
      "TicketBulkResult": {
        "type": "object",
        "required": [
          "id",
          "result"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "O item como foi enviado (o contato, no caso de `{contact, name}`)."
          },
          "result": {
            "type": "string",
            "enum": [
              "applied",
              "skipped",
              "error"
            ]
          },
          "error": {
            "type": "string",
            "description": "Por que o item não mudou (`skipped` ou `error`)."
          },
          "ticket": {
            "$ref": "#/components/schemas/Ticket"
          }
        }
      },
      "TicketEvent": {
        "type": "object",
        "required": [
          "id",
          "ticket_id",
          "action",
          "via",
          "actor",
          "reason",
          "before",
          "after",
          "event_id",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "ticket_id": {
            "type": "string",
            "format": "uuid"
          },
          "action": {
            "type": "string",
            "enum": [
              "opened",
              "resolved",
              "reopened",
              "assigned",
              "pending_set",
              "pending_cleared"
            ]
          },
          "via": {
            "type": "string",
            "enum": [
              "console",
              "api",
              "system"
            ],
            "description": "`console` (pessoa no console), `api` (chave de API) ou `system` (aberto por mensagem recebida)."
          },
          "actor": {
            "type": "object",
            "required": [
              "user_id",
              "name",
              "api_key_id",
              "label"
            ],
            "properties": {
              "user_id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A pessoa (pela API, quem criou a chave); `null` para o sistema ou chave sem pessoa."
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Nome (ou e-mail) da pessoa; `null` sem pessoa ou se ela foi removida."
              },
              "api_key_id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A chave de API usada (`via: api`)."
              },
              "label": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "O `actor_label` enviado: o atendente no sistema do integrador, como enviado (não verificado)."
              }
            },
            "additionalProperties": false
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "before": {
            "$ref": "#/components/schemas/TicketEventState"
          },
          "after": {
            "$ref": "#/components/schemas/TicketEventState"
          },
          "event_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "O `event_id` do evento de webhook (`ticket.*`) anunciado com esta mudança."
          },
          "created_at": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "TicketEventState": {
        "type": "object",
        "description": "Só os campos que a mudança tocou; nunca o contato.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "open",
              "resolved"
            ]
          },
          "assigned_user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "pending": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "level",
              "note"
            ],
            "properties": {
              "level": {
                "type": "string",
                "enum": [
                  "urgent",
                  "medium",
                  "low"
                ]
              },
              "note": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "additionalProperties": false
          },
          "resolved_by_user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "reopen_count": {
            "type": "integer"
          }
        },
        "additionalProperties": false
      },
      "TicketOpenInput": {
        "type": "object",
        "required": [
          "contact"
        ],
        "properties": {
          "contact": {
            "type": "string",
            "maxLength": 64,
            "description": "Telefone E.164 (`+55…`), contato `…@lid` ou grupo `group:<jid>` (por exemplo `group:120363000000000001@g.us`). Grupo não entra no funil e nunca recebe a pesquisa de satisfação."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "description": "Nome do grupo, devolvido como `contact` do atendimento (sem nome, `Grupo`). Ignorado para pessoas."
          },
          "reason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 280,
            "description": "Motivo da mudança, guardado no histórico do atendimento."
          },
          "actor_label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Nome do atendente no seu sistema, guardado no histórico como enviado (declarado, não verificado)."
          }
        },
        "additionalProperties": false
      },
      "TicketPendingInput": {
        "type": "object",
        "required": [
          "level"
        ],
        "properties": {
          "level": {
            "type": "string",
            "enum": [
              "urgent",
              "medium",
              "low"
            ]
          },
          "note": {
            "type": "string",
            "minLength": 1,
            "maxLength": 280,
            "description": "Observação opcional."
          },
          "reason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 280,
            "description": "Motivo da mudança, guardado no histórico do atendimento."
          },
          "actor_label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Nome do atendente no seu sistema, guardado no histórico como enviado (declarado, não verificado)."
          }
        },
        "additionalProperties": false
      },
      "TicketResolveInput": {
        "type": "object",
        "properties": {
          "send_csat": {
            "type": "boolean",
            "description": "`false`: não envia a pesquisa de satisfação desta vez. Sem o campo, segue a configuração do número."
          },
          "reason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 280,
            "description": "Motivo da mudança, guardado no histórico do atendimento."
          },
          "actor_label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Nome do atendente no seu sistema, guardado no histórico como enviado (declarado, não verificado)."
          }
        },
        "additionalProperties": false
      },
      "TicketTrailInput": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 280,
            "description": "Motivo da mudança, guardado no histórico do atendimento."
          },
          "actor_label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Nome do atendente no seu sistema, guardado no histórico como enviado (declarado, não verificado)."
          }
        },
        "additionalProperties": false
      },
      "UpdateLaunchLinkInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "groups": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/GroupJid"
            }
          },
          "cap": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1024
          },
          "active": {
            "type": "boolean"
          },
          "auto_create": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/AutoCreateInput"
              },
              {
                "type": "null"
              }
            ],
            "description": "null desliga e esquece o modelo. Enviar de novo limpa `auto_create.error`."
          }
        },
        "additionalProperties": false
      },
      "UserJid": {
        "type": "string",
        "pattern": "^\\d{5,20}@(s\\.whatsapp\\.net|lid)$",
        "description": "JID de pessoa: `5511912345678@s.whatsapp.net` ou `<id>@lid`."
      },
      "WebhookDelivery": {
        "type": "object",
        "required": [
          "id",
          "endpoint_id",
          "event_id",
          "event_type",
          "instance_id",
          "state",
          "attempts",
          "round",
          "next_attempt_at",
          "last_status",
          "last_error_code",
          "delivered_at",
          "dead_at",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "endpoint_id": {
            "type": "string",
            "format": "uuid"
          },
          "event_id": {
            "type": "string",
            "format": "uuid"
          },
          "event_type": {
            "$ref": "#/components/schemas/EventType"
          },
          "instance_id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "pending",
              "sending",
              "delivered",
              "dead",
              "held"
            ],
            "description": "`held`: guardada enquanto o endereço está pausado."
          },
          "attempts": {
            "type": "integer",
            "minimum": 0,
            "maximum": 8,
            "description": "Tentativas da rodada atual."
          },
          "round": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "description": "Rodada de entrega: 1, e +1 a cada `POST /v1/webhook-deliveries/{id}/retry`."
          },
          "next_attempt_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_status": {
            "type": [
              "integer",
              "null"
            ]
          },
          "last_error_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Ex.: `delivery_unconfirmed`, `client_error`, `endpoint_unauthorized`, `endpoint_gone`, `destination_blocked`, `held_expired`, `endpoint_disabled`."
          },
          "delivered_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "dead_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "WebhookDeliveryList": {
        "type": "object",
        "required": [
          "data",
          "next_cursor"
        ],
        "properties": {
          "data": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/WebhookDelivery"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Passe em `cursor` para a próxima página (mais antigas). `null`: não há mais."
          }
        },
        "additionalProperties": false
      },
      "WebhookEndpoint": {
        "type": "object",
        "required": [
          "id",
          "workspace_id",
          "url",
          "state",
          "secret_kid",
          "event_types",
          "instance_ids",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "active",
              "paused",
              "disabled"
            ],
            "description": "`paused`: pausado por você ou pelo FlowZap (destino bloqueado, ou 401/403 três vezes); os avisos ficam guardados. `disabled`: removido (ou respondeu 410)."
          },
          "secret_kid": {
            "type": "string",
            "format": "uuid",
            "description": "Identificador do segredo; aparece na assinatura."
          },
          "event_types": {
            "$ref": "#/components/schemas/WebhookEventTypes"
          },
          "instance_ids": {
            "$ref": "#/components/schemas/WebhookInstanceIds"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "WebhookEndpointCreated": {
        "type": "object",
        "required": [
          "id",
          "workspace_id",
          "url",
          "state",
          "secret_kid",
          "event_types",
          "instance_ids",
          "created_at",
          "updated_at",
          "secret"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "active"
            ]
          },
          "secret_kid": {
            "type": "string",
            "format": "uuid"
          },
          "event_types": {
            "$ref": "#/components/schemas/WebhookEventTypes"
          },
          "instance_ids": {
            "$ref": "#/components/schemas/WebhookInstanceIds"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "secret": {
            "type": "string",
            "description": "Segredo (base64url) para conferir a assinatura. Aparece só nesta resposta."
          }
        },
        "additionalProperties": false
      },
      "WebhookEndpointDetail": {
        "type": "object",
        "required": [
          "id",
          "workspace_id",
          "url",
          "state",
          "secret_kid",
          "event_types",
          "instance_ids",
          "created_at",
          "updated_at",
          "held_deliveries"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "active",
              "paused",
              "disabled"
            ]
          },
          "secret_kid": {
            "type": "string",
            "format": "uuid"
          },
          "event_types": {
            "$ref": "#/components/schemas/WebhookEventTypes"
          },
          "instance_ids": {
            "$ref": "#/components/schemas/WebhookInstanceIds"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "held_deliveries": {
            "type": "integer",
            "minimum": 0,
            "description": "Avisos guardados (`held`) esperando o endereço voltar a `active`."
          }
        },
        "additionalProperties": false
      },
      "WebhookEndpointInput": {
        "type": "object",
        "required": [
          "workspace_id",
          "url"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "description": "Endereço https público que recebe os avisos."
          },
          "event_types": {
            "$ref": "#/components/schemas/WebhookEventTypes"
          },
          "instance_ids": {
            "$ref": "#/components/schemas/WebhookInstanceIds"
          }
        },
        "additionalProperties": false
      },
      "WebhookEndpointPatch": {
        "type": "object",
        "minProperties": 1,
        "description": "Só os campos enviados mudam. `null` em `event_types` ou `instance_ids` tira o filtro.",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "description": "Novo endereço https público (conferido de novo contra destinos privados)."
          },
          "event_types": {
            "$ref": "#/components/schemas/WebhookEventTypes"
          },
          "instance_ids": {
            "$ref": "#/components/schemas/WebhookInstanceIds"
          },
          "state": {
            "type": "string",
            "enum": [
              "active",
              "paused"
            ],
            "description": "`paused`: os avisos novos ficam guardados (`held`). `active`: volta a entregar; os guardados dos últimos 7 dias são entregues, os mais antigos viram `dead` (`held_expired`)."
          }
        },
        "additionalProperties": false
      },
      "WebhookEndpointUpdated": {
        "type": "object",
        "required": [
          "id",
          "workspace_id",
          "url",
          "state",
          "secret_kid",
          "event_types",
          "instance_ids",
          "created_at",
          "updated_at",
          "released_deliveries"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "active",
              "paused"
            ]
          },
          "secret_kid": {
            "type": "string",
            "format": "uuid"
          },
          "event_types": {
            "$ref": "#/components/schemas/WebhookEventTypes"
          },
          "instance_ids": {
            "$ref": "#/components/schemas/WebhookInstanceIds"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "released_deliveries": {
            "type": "integer",
            "minimum": 0,
            "description": "Avisos guardados que voltaram para a fila nesta mudança (só ao passar de `paused` para `active`)."
          }
        },
        "additionalProperties": false
      },
      "WebhookEvent": {
        "type": "object",
        "description": "Corpo do aviso. Traz só tipo e IDs; o conteúdo é lido pela API com a sua chave.",
        "required": [
          "event_id",
          "schema_version",
          "type",
          "occurred_at",
          "organization_id",
          "workspace_id",
          "instance_id",
          "sequence",
          "data"
        ],
        "properties": {
          "event_id": {
            "type": "string",
            "format": "uuid"
          },
          "schema_version": {
            "type": "string",
            "description": "Versão do formato (ex.: `1.0`)."
          },
          "type": {
            "type": "string",
            "description": "Tipo do evento (veja `EventType`, mais `message.canceled`)."
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time"
          },
          "organization_id": {
            "type": "string",
            "format": "uuid"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "instance_id": {
            "type": "string",
            "format": "uuid"
          },
          "sequence": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "required": [
              "resource_id"
            ],
            "properties": {
              "resource_id": {
                "type": "string",
                "format": "uuid"
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "WebhookEventTypes": {
        "type": [
          "array",
          "null"
        ],
        "description": "Tipos que este endereço recebe (1 a 100, do catálogo de eventos; repetidos são ignorados). `null` = todos os tipos, inclusive os que forem criados depois.",
        "minItems": 1,
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/EventType"
        }
      },
      "WebhookInstanceIds": {
        "type": [
          "array",
          "null"
        ],
        "description": "Números (IDs) da área de trabalho que este endereço recebe (1 a 100). `null` = todos os números da área, inclusive os criados depois. Número de outra área: 400 `instance_not_in_workspace`.",
        "minItems": 1,
        "maxItems": 100,
        "items": {
          "type": "string",
          "format": "uuid"
        }
      },
      "WebhookPingBody": {
        "type": "object",
        "description": "Corpo do aviso de teste que o seu endereço recebe (mesmos cabeçalhos e assinatura de um aviso real). Não é guardado nem aparece no histórico.",
        "required": [
          "event_id",
          "schema_version",
          "type",
          "occurred_at",
          "organization_id",
          "workspace_id",
          "instance_id",
          "sequence",
          "data"
        ],
        "properties": {
          "event_id": {
            "type": "string",
            "format": "uuid"
          },
          "schema_version": {
            "type": "string",
            "enum": [
              "1.0"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "webhook.ping"
            ]
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time"
          },
          "organization_id": {
            "type": "string",
            "format": "uuid"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "instance_id": {
            "type": "null"
          },
          "sequence": {
            "type": "integer",
            "enum": [
              0
            ]
          },
          "data": {
            "type": "object",
            "required": [
              "resource_id"
            ],
            "properties": {
              "resource_id": {
                "type": "null"
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "WebhookPingResult": {
        "type": "object",
        "required": [
          "delivered",
          "status",
          "duration_ms",
          "error_code"
        ],
        "properties": {
          "delivered": {
            "type": "boolean",
            "description": "true quando o seu endereço respondeu 2xx."
          },
          "status": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Status HTTP da resposta; null quando não houve resposta."
          },
          "duration_ms": {
            "type": "integer",
            "minimum": 0
          },
          "error_code": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              null,
              "unexpected_status",
              "destination_blocked",
              "dns_failed",
              "timeout",
              "connection_failed"
            ],
            "description": "null quando entregou. `unexpected_status`: respondeu, mas não 2xx. `destination_blocked`: o endereço resolve para rede privada. `dns_failed`, `timeout`, `connection_failed`: sem resposta."
          }
        },
        "additionalProperties": false
      },
      "WhatsappLabel": {
        "type": "object",
        "required": [
          "label_id",
          "name",
          "color",
          "updated_at"
        ],
        "properties": {
          "label_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "color": {
            "type": "integer",
            "minimum": 0,
            "maximum": 19
          },
          "updated_at": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "Window": {
        "type": "object",
        "description": "Listas, contagem e busca usam o histórico guardado pelo FlowZap, limitado às 2000 mensagens mais recentes de cada origem (enviadas pela API e recebidas/vistas pelo número) — `rows_per_source`. `truncated` indica que há mensagens mais antigas fora dessa janela; `skipped`, registros que não puderam ser lidos. As mensagens de uma conversa (`GET …/chats/{jid}/messages`) não dependem da janela (veja `paging`).",
        "required": [
          "rows_per_source",
          "truncated",
          "skipped"
        ],
        "properties": {
          "rows_per_source": {
            "type": "integer"
          },
          "truncated": {
            "type": "boolean"
          },
          "skipped": {
            "type": "integer",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "Workspace": {
        "type": "object",
        "required": [
          "id",
          "organization_id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "organization_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          }
        },
        "additionalProperties": false
      }
    },
    "responses": {
      "AccountRateLimited": {
        "description": "`rate_limited`: a organização passou dos pedidos por minuto do plano (todas as chaves somadas). Espere o tempo de `Retry-After`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitLimit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitRemaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitReset"
          }
        }
      },
      "BillingForbidden": {
        "description": "`scope_denied`: falta o escopo da rota, ou a chave está presa a uma área de trabalho ou número (a cobrança é da conta inteira). `billing_role_required`: quem criou a chave não é (mais) dono nem responsável pela cobrança da conta. `organization_suspended`: conta suspensa ou encerrada. `plan_feature_required`: o plano não inclui a API.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "CheckoutLink": {
        "description": "Cobrança criada no checkout do Asaas. **O pagamento acontece na página do Asaas** (`link`); o FlowZap nunca recebe dados de cartão. A liberação vem depois do pagamento confirmado.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "data"
              ],
              "properties": {
                "data": {
                  "type": "object",
                  "required": [
                    "checkout_id",
                    "link"
                  ],
                  "properties": {
                    "intent_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Primeira contratação."
                    },
                    "cycle_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Renovação."
                    },
                    "change_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Aumento de ligações ou de Gravações no FlowZap."
                    },
                    "checkout_id": {
                      "type": "string",
                      "description": "ID do checkout no Asaas."
                    },
                    "link": {
                      "type": "string",
                      "format": "uri",
                      "description": "Página de pagamento do Asaas."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "CheckoutPending": {
        "description": "`state: needs_review`: o Asaas não confirmou se criou o checkout. **Não repita com outra chave**: a mesma chave nunca cria outro checkout; a equipe FlowZap confere, e o resumo (`GET /v1/billing/subscription`) mostra o link quando houver.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "data"
              ],
              "properties": {
                "data": {
                  "type": "object",
                  "required": [
                    "state"
                  ],
                  "properties": {
                    "state": {
                      "type": "string",
                      "enum": [
                        "needs_review"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      },
      "CheckoutRateLimited": {
        "description": "`rate_limited`: mais de 10 pedidos desta operação em 15 minutos pela mesma pessoa (o limite do console vale para a chave de quem a criou), ou pedidos por minuto do plano. Espere o tempo de `Retry-After` quando houver.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "CheckoutUnavailable": {
        "description": "`checkout_unavailable`: a venda está desligada agora. `card_checkout_unavailable`: cartão não disponível. `provider_rate_limited`: o Asaas pediu para esperar (`Retry-After`). `checkout_offer_unavailable`: a oferta não está mais à venda.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "EngineTimeout": {
        "description": "`engine_timeout`: a operação venceu antes de o número executá-la. Nada foi feito; pode repetir.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Error": {
        "description": "Erro. Veja `error.code`.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "`not_found`: não existe, ou a chave não tem acesso a esta área de trabalho ou número.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotSupported": {
        "description": "`not_supported_by_engine`: o WhatsApp Web não oferece este recurso. `retryable` é false.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "OperationFailed": {
        "description": "A operação terminou com falha no WhatsApp; `error.code` traz o motivo informado pelo motor.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "OperationPending": {
        "description": "Ainda em andamento (a espera é de até 15 s). Consulte o endereço do cabeçalho `Location` depois de `Retry-After` segundos.",
        "headers": {
          "Location": {
            "$ref": "#/components/headers/Location"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/OperationPending"
            }
          }
        }
      },
      "OutcomeUnknown": {
        "description": "`outcome_unknown` (ou outro código do motor): o WhatsApp pode ter aplicado a mudança ou não. **Não repita às cegas**: confira o estado antes.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "`rate_limited`: mais de 60 envios por minuto (rajada de 10) com a mesma chave e número. `queue_full`: a fila do número já tem os envios aguardando que o plano permite. Espere o tempo de `Retry-After`. Repetir com uma `Idempotency-Key` já aceita nos últimos 10 minutos não conta no limite.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        }
      },
      "ScopeDenied": {
        "description": "`scope_denied`: a chave não tem o escopo desta rota. `organization_suspended`: a conta da chave está suspensa ou encerrada; nenhuma rota responde até a conta ser reativada pela equipe FlowZap.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "`unauthorized`: chave ausente, inválida, revogada ou vencida.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Chave única por pedido (letras, números, `_ . : -`, até 128). Repetir com a mesma chave devolve o mesmo resultado sem refazer; com conteúdo diferente, 409 `idempotency_conflict`. Opcional nesta rota.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[a-zA-Z0-9_.:-]{1,128}$"
        }
      },
      "IdempotencyKeyRequired": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "Chave única por pedido (letras, números, `_ . : -`, até 128). Repetir com a mesma chave devolve o mesmo resultado sem refazer; com conteúdo diferente, 409 `idempotency_conflict`.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[a-zA-Z0-9_.:-]{1,128}$"
        }
      },
      "InstanceId": {
        "name": "instanceId",
        "in": "path",
        "required": true,
        "description": "ID do número.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "WorkspaceId": {
        "name": "workspaceId",
        "in": "path",
        "required": true,
        "description": "ID da área de trabalho.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "headers": {
      "IdempotentReplay": {
        "description": "`true` quando a resposta repete um pedido já atendido com a mesma `Idempotency-Key`.",
        "schema": {
          "type": "string",
          "enum": [
            "true"
          ]
        }
      },
      "Location": {
        "description": "`/v1/operations/{id}` da operação em andamento.",
        "schema": {
          "type": "string"
        }
      },
      "RateLimitLimit": {
        "description": "Pedidos por minuto do plano, somando todas as chaves da organização.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimitRemaining": {
        "description": "Pedidos que ainda cabem no minuto atual.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimitReset": {
        "description": "Segundos até o minuto atual terminar.",
        "schema": {
          "type": "integer"
        }
      },
      "RequestId": {
        "description": "Identificador da resposta (o enviado pelo cliente em `X-Request-Id`, quando válido, ou um UUID gerado). Igual a `error.request_id`; presente em toda resposta.",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9._:-]{8,128}$"
        }
      },
      "RetryAfter": {
        "description": "Segundos até poder tentar de novo.",
        "schema": {
          "type": "integer"
        }
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "fzk_<prefixo>_<segredo>",
        "description": "Chave de API. Aparece uma única vez, ao ser criada."
      }
    }
  }
}
