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
pixTypeaceita:CPF,CNPJ,PHONE,EMAIL,EVP(case insensitive)pixNamepadrã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
{
"number": "5511999999999",
"pixType": "EVP",
"pixKey": "123e4567-e89b-12d3-a456-426614174000",
"pixName": "Loja Exemplo"
}
Autenticação
[
{
"token": []
}
]
{
"token": {
"name": "token",
"type": "apiKey",
"in": "header"
}
}
Corpo da requisição
{
"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
{
"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
{
"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."
}
}
}