# Enviar botão PIX POST /send/pix-button Envia um botão nativo do WhatsApp que abre para pagamento PIX com a chave informada. O usuário visualiza o detalhe do recebedor, nome e chave. ## Regras principais - `pixType` aceita: `CPF`, `CNPJ`, `PHONE`, `EMAIL`, `EVP` (case insensitive) - `pixName` padrão: `"Pix"` quando não informado - nome de quem recebe o pagamento ## Campos comuns Este endpoint herda os campos opcionais padronizados da tag **"Enviar Mensagem"**: `delay`, `readchat`, `readmessages`, `replyid`, `mentions`, `track_source`, `track_id` e `async`. ## Exemplo de payload ```json { "number": "5511999999999", "pixType": "EVP", "pixKey": "123e4567-e89b-12d3-a456-426614174000", "pixName": "Loja Exemplo" } ``` ## Autenticação ```json [ { "token": [] } ] ``` ```json { "token": { "name": "token", "type": "apiKey", "in": "header" } } ``` ## Corpo da requisição ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "string", "description": "ID do chat para o qual a mensagem será enviada. Pode ser um número de telefone em formato internacional, um ID de grupo (`@g.us`), um ID de usuário (com `@s.whatsapp.net` ou `@lid`).", "example": "5511999999999" }, "pixType": { "type": "string", "description": "Tipo da chave PIX. Valores aceitos: CPF, CNPJ, PHONE, EMAIL ou EVP", "example": "EVP" }, "pixKey": { "type": "string", "description": "Valor da chave PIX (CPF/CNPJ/telefone/email/EVP)", "example": "123e4567-e89b-12d3-a456-426614174000" }, "pixName": { "type": "string", "description": "Nome exibido como recebedor do PIX (padrão \"Pix\" se vazio)", "example": "Loja Exemplo" }, "async": { "type": "boolean", "description": "Enfileira o envio para processamento assíncrono" }, "delay": { "type": "integer", "description": "Atraso em milissegundos antes do envio (exibe \"digitando...\" no WhatsApp)" }, "readchat": { "type": "boolean", "description": "Marca o chat como lido após enviar a mensagem" }, "readmessages": { "type": "boolean", "description": "Marca mensagens recentes como lidas após o envio" }, "replyid": { "type": "string", "description": "ID da mensagem que será respondida" }, "mentions": { "type": "string", "description": "Lista de números mencionados separados por vírgula" }, "track_source": { "type": "string", "description": "Origem de rastreamento (ex.: chatwoot, crm-interno)" }, "track_id": { "type": "string", "description": "Identificador de rastreamento (aceita valores duplicados)" } }, "required": [ "number", "pixType", "pixKey" ], "example": { "number": "5511999999999", "pixType": "EVP", "pixKey": "123e4567-e89b-12d3-a456-426614174000", "pixName": "Loja Exemplo" } } } } } ``` ## Respostas ```json { "200": { "description": "Botão PIX enviado com sucesso", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Message" }, { "type": "object", "properties": { "response": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "PIX button sent successfully" } } } } } ] } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid keyType. Allowed: CPF, CNPJ, PHONE, EMAIL, EVP" } } } } } }, "401": { "description": "Não autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid token" } } } } } }, "500": { "description": "Erro interno do servidor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Failed to send PIX button" } } } } } } } ``` ## #/components/schemas/Message ```json { "type": "object", "description": "Representa uma mensagem trocada no sistema", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID único interno da mensagem (formato r + 7 caracteres hex aleatórios)" }, "messageid": { "type": "string", "description": "ID original da mensagem no provedor" }, "chatid": { "type": "string", "description": "ID da conversa relacionada" }, "sender": { "type": "string", "description": "ID do remetente da mensagem" }, "senderName": { "type": "string", "description": "Nome exibido do remetente" }, "isGroup": { "type": "boolean", "description": "Indica se é uma mensagem de grupo", "default": false }, "fromMe": { "type": "boolean", "description": "Indica se a mensagem foi enviada pelo usuário", "default": false }, "messageType": { "type": "string", "description": "Tipo de conteúdo da mensagem" }, "source": { "type": "string", "description": "Plataforma de origem da mensagem" }, "messageTimestamp": { "type": "integer", "description": "Timestamp original da mensagem em milissegundos", "default": 0 }, "status": { "type": "string", "description": "Status do ciclo de vida da mensagem.\nExemplos comuns: `Queued`, `Canceled`, `Failed`, `Sent`, `Delivered`, `Read`.\n" }, "text": { "type": "string", "description": "Texto original da mensagem", "default": "" }, "quoted": { "type": "string", "description": "ID da mensagem citada/respondida", "default": "" }, "edited": { "type": "string", "description": "Histórico de edições da mensagem", "default": "" }, "reaction": { "type": "string", "description": "ID da mensagem reagida", "default": "" }, "vote": { "type": "string", "description": "Dados de votação de enquete e listas", "default": "" }, "convertOptions": { "type": "string", "description": "Conversão de opções da mensagem, lista, enquete e botões", "default": "" }, "buttonOrListid": { "type": "string", "description": "ID do botão ou item de lista selecionado", "default": "" }, "owner": { "type": "string", "description": "Dono da mensagem", "default": "" }, "error": { "type": "string", "description": "Mensagem de erro caso o envio tenha falhado", "default": "" }, "content": { "description": "Conteúdo bruto da mensagem (JSON serializado ou texto)", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "string", "description": "Texto bruto quando não for JSON" } ] }, "wasSentByApi": { "type": "boolean", "description": "Indica se a mensagem foi enviada via API" }, "sendFunction": { "type": "string", "description": "Função usada para enviar a mensagem (quando enviada via API)" }, "sendPayload": { "description": "Payload usado no envio quando disponível. Dados de mídia em base64 são omitidos.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "string", "description": "Texto bruto quando não for JSON" } ] }, "fileURL": { "type": "string", "description": "URL ou referência de arquivo da mensagem" }, "callPeer": { "type": "object", "description": "Contato conhecido associado a uma ligação, quando disponível em `messageType: call`.", "properties": { "jid": { "type": "string" }, "name": { "type": "string" }, "imagePreviewUrl": { "type": "string" } } }, "send_folder_id": { "type": "string", "description": "Pasta associada ao envio (quando aplicável)" }, "track_source": { "type": "string", "description": "Origem de rastreamento" }, "track_id": { "type": "string", "description": "ID de rastreamento (pode repetir)" }, "ai_metadata": { "type": "object", "description": "Metadados do processamento por IA", "properties": { "agent_id": { "type": "string", "description": "ID do agente de IA responsável" }, "request": { "type": "object", "description": "Dados da requisição à API de IA", "properties": { "messages": { "type": "array", "description": "Histórico de mensagens enviadas para a API" }, "tools": { "type": "array", "description": "Ferramentas disponíveis para o agente" }, "options": { "type": "object", "description": "Opções de configuração da API", "properties": { "model": { "type": "string" }, "temperature": { "type": "number" }, "maxTokens": { "type": "integer" }, "topP": { "type": "number" }, "frequencyPenalty": { "type": "number" }, "presencePenalty": { "type": "number" } } } } }, "response": { "type": "object", "description": "Resposta da API de IA", "properties": { "choices": { "type": "array", "description": "Resultados retornados pela API" }, "toolResults": { "type": "array", "description": "Resultados da execução de ferramentas" }, "error": { "type": "string", "description": "Mensagem de erro, se houver" } } } } }, "sender_pn": { "description": "JID PN resolvido do remetente (quando disponível)", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "sender_lid": { "description": "LID original do remetente (quando disponível)", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "sender_image_preview_url": { "type": "string", "format": "uri", "description": "URL temporária de preview do remetente, quando conhecida. A hidratação desta versão preenche mensagens recebidas em grupos; o campo pode ser omitido. Não provoca consulta de foto ao WhatsApp na listagem." } } } ``` ## Guias relacionados [Autenticação](/docs/authentication) · [Erros e retries](/docs/errors-and-retries) · [Server URL](/docs/server-url)