> ## Documentation Index > Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Configurar Formulário Instantâneo > Cria ou substitui a configuração de um formulário: qual caixa de consentimento significa "pode me mandar mensagem no WhatsApp" e se todo lead novo do formulário recebe uma **mensagem automática no WhatsApp** — enviada pela Pilot Status sem um humano, então uma configuração aceita por este endpoint vai mandar mensagem aos leads. Envie o objeto inteiro. Regras: o envio automático exige `consentDisclaimerKey` (`400 CONSENT_REQUIRED`). Num número **oficial** a mensagem é um template APROVADO do número (`templateId`; `400 TEMPLATE_REQUIRED`, `TEMPLATE_NOT_ELIGIBLE`, `FREE_TEXT_NOT_ALLOWED`). Num número **não oficial** é `freeText` com variáveis `{{nome}}` (`400 FREE_TEXT_REQUIRED`, `TEMPLATE_NOT_ALLOWED`; uma variável com espaços é recusada como `VALIDATION_FAILED` com `INVALID_PLACEHOLDER`). Toda variável precisa estar mapeada em `variableMap` para uma resposta do formulário (`{ "source": "field", "key": "" }`) ou um valor fixo (`{ "source": "static", "value": "..." }`) — senão, `400 VARIABLES_UNMAPPED` com `missingVariables`. As regras da mensagem só valem com `autoSendEnabled: true`, então você pode salvar a caixa de consentimento e um rascunho antes. Tokens OAuth/MCP precisam de `integrations:manage` (ADMIN ou OWNER do workspace) em todos os verbos, leituras incluídas. Escopo: uma chave com escopo de número, ou uma credencial da conta inteira com `x-whatsapp-number-id`, atua só nos vínculos daquele número; uma credencial da conta inteira sem o header vê o workspace todo. ## OpenAPI ````yaml openapi.pt.json PUT /v1/lead-pages/{pageLinkId}/forms/{formId} openapi: 3.1.0 info: title: API Pilot Status version: 1.0.0 license: name: Pilot Status Terms of Service url: https://pilotstatus.com.br/terms description: >- API REST pública do Pilot Status. Autentique com o header `x-api-key: ps_...` (ou `x-api-key-id`). Base URL: https://pilotstatus.com.br servers: - url: https://pilotstatus.com.br security: - apiKey: [] - apiKeyId: [] paths: /v1/lead-pages/{pageLinkId}/forms/{formId}: put: tags: - Ads summary: Configurar Formulário Instantâneo description: >- Cria ou substitui a configuração de um formulário: qual caixa de consentimento significa "pode me mandar mensagem no WhatsApp" e se todo lead novo do formulário recebe uma **mensagem automática no WhatsApp** — enviada pela Pilot Status sem um humano, então uma configuração aceita por este endpoint vai mandar mensagem aos leads. Envie o objeto inteiro. Regras: o envio automático exige `consentDisclaimerKey` (`400 CONSENT_REQUIRED`). Num número **oficial** a mensagem é um template APROVADO do número (`templateId`; `400 TEMPLATE_REQUIRED`, `TEMPLATE_NOT_ELIGIBLE`, `FREE_TEXT_NOT_ALLOWED`). Num número **não oficial** é `freeText` com variáveis `{{nome}}` (`400 FREE_TEXT_REQUIRED`, `TEMPLATE_NOT_ALLOWED`; uma variável com espaços é recusada como `VALIDATION_FAILED` com `INVALID_PLACEHOLDER`). Toda variável precisa estar mapeada em `variableMap` para uma resposta do formulário (`{ "source": "field", "key": "" }`) ou um valor fixo (`{ "source": "static", "value": "..." }`) — senão, `400 VARIABLES_UNMAPPED` com `missingVariables`. As regras da mensagem só valem com `autoSendEnabled: true`, então você pode salvar a caixa de consentimento e um rascunho antes. Tokens OAuth/MCP precisam de `integrations:manage` (ADMIN ou OWNER do workspace) em todos os verbos, leituras incluídas. Escopo: uma chave com escopo de número, ou uma credencial da conta inteira com `x-whatsapp-number-id`, atua só nos vínculos daquele número; uma credencial da conta inteira sem o header vê o workspace todo. operationId: put_lead-page-form parameters: - name: pageLinkId in: path required: true description: >- O id do vínculo (`linked[].pageLinkId` de `GET /v1/lead-pages`), não o id da Página do Facebook. schema: type: string example: cmgpl0001ab12cd34ef56 - name: formId in: path required: true description: Id numérico do Formulário Instantâneo (`forms[].formId`). schema: type: string example: '987654321098765' - name: x-whatsapp-number-id in: header required: false description: >- Restringe uma credencial da conta inteira a um número (o id dele ou o id da instância, de `GET /v1/numbers`). Sem ele, uma credencial da conta inteira vê o workspace todo; uma chave com escopo de número vê sempre só o próprio número. schema: type: string example: num_01HZX... requestBody: required: true content: application/json: schema: type: object properties: consentDisclaimerKey: type: - string - 'null' description: >- `key` da caixa de consentimento (`consentCheckboxes[].key`). Obrigatória para o envio automático. example: whatsapp_optin autoSendEnabled: type: boolean description: >- Mandar mensagem automaticamente a todo lead novo do formulário. example: true templateId: type: - string - 'null' description: >- Números oficiais: um template APROVADO do número (`templates[].id`). Deve ser `null` em números não oficiais. example: null freeText: type: - string - 'null' maxLength: 4096 description: >- Números não oficiais: a mensagem, com variáveis `{{nome}}`. Deve ser `null` em números oficiais. example: Olá {{nome}}, recebemos seu pedido de orçamento! variableMap: type: object description: >- Valor de cada variável do template ou do texto: `{ "source": "field", "key": "" }` ou `{ "source": "static", "value": "..." }`. Padrão `{}`. additionalProperties: type: object example: nome: source: field key: full_name formName: type: - string - 'null' maxLength: 255 description: Rótulo opcional do formulário. example: Orçamento — Outubro required: - consentDisclaimerKey - autoSendEnabled - templateId - freeText additionalProperties: false responses: '200': description: Configuração salva content: application/json: example: config: formId: '987654321098765' formName: Orçamento — Outubro consentDisclaimerKey: whatsapp_optin autoSendEnabled: true templateId: null freeText: Olá {{nome}}, recebemos seu pedido de orçamento! variableMap: nome: source: field key: full_name updatedAt: '2026-10-21T09:30:00.000Z' '400': description: >- `INVALID_BODY`, `UNKNOWN_FIELDS`, `VALIDATION_FAILED` (`formId` ou corpo inválido, com `details`), ou uma recusa de regra: `CONSENT_REQUIRED`, `TEMPLATE_REQUIRED`, `TEMPLATE_NOT_ELIGIBLE`, `TEMPLATE_NOT_ALLOWED`, `FREE_TEXT_REQUIRED`, `FREE_TEXT_NOT_ALLOWED`, `VARIABLES_UNMAPPED` (com `missingVariables`); também `NUMBER_REQUIRED` (concessão OAuth por número sem `x-whatsapp-number-id`) ou `NUMBER_NOT_FOUND` (chave com escopo de número cujo número foi apagado) content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- Every variable in the text needs a value. | Todas as variáveis do texto precisam de um valor. code: VARIABLES_UNMAPPED missingVariables: - cidade '401': description: Header `x-api-key` / `x-api-key-id` ausente ou inválido content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Unauthorized '403': description: >- O número está fora do escopo da credencial (`NUMBER_NOT_IN_GRANT`), ou token OAuth cujo papel no workspace não tem `integrations:manage` (`PERMISSION_DENIED`) content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- This credential is not granted access to that WhatsApp number | Esta credencial não tem acesso a esse número de WhatsApp code: NUMBER_NOT_IN_GRANT '404': description: >- Vínculo de página não encontrado: nunca vinculado, já desvinculado ou de outro workspace content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Page link not found | Vínculo de página não encontrado code: NOT_FOUND '500': description: Erro interno content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Internal server error | Erro interno do servidor code: INTERNAL_ERROR components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Sua chave de API ps_ apiKeyId: type: apiKey in: header name: x-api-key-id description: Id da chave de API (alternativa ao x-api-key) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.