curl --request POST \
--url https://api.wppfy.com/instance/connect \
--header 'Content-Type: application/json' \
--header 'token: <api-key>' \
--data '
{
"browser": "auto",
"systemName": "Minha Empresa",
"proxy_managed_country": "br",
"proxy_managed_state": "sp",
"proxy_managed_city": "campinas"
}
'{
"response": "Connecting",
"request_id": "5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f",
"status": {
"connected": false,
"loggedIn": false,
"jid": null
}
}Conectar instância ao WhatsApp
Inicia a conexão da instância com o WhatsApp.
- Sem
phone, retorna um QR Code para leitura no celular. - Com
phone, retorna um código de pareamento para esse número.
A instância permanece em connecting até o pareamento ser confirmado ou o
prazo expirar. Acompanhe a evolução em GET /instance/status; não repita a
chamada enquanto o processo estiver em andamento.
Após a conexão, o histórico disponível começa a chegar pelo evento
history e pode ser consultado em POST /message/find e POST /chat/find.
A resposta pode incluir request_id no topo, antes mesmo da leitura do QR code
ou do código de pareamento. Guarde esse id para correlacionar a tentativa com
os lotes history do pareamento, inclusive o status de conclusão, e com
GET /instance/history-sync/status. Ele permanece igual durante a mesma
tentativa e muda a cada novo pareamento. Pode estar ausente quando não há
pareamento nem rastreamento disponível.
Em um pareamento novo, history_days escolhe quantos dias de histórico o
celular envia. Sem o campo, com valor fora de 0–365 ou de 1 a 90 dias, o
pedido é o histórico normal (90 dias, quando não há um valor válido). De 91
a 365 dias, ou com 0 (o máximo, 365 dias), o pedido é o histórico
completo, maior e mais demorado. Uma instância já pareada reconecta sem
pedir histórico.
Para escolher uma região de conexão, consulte primeiro
GET /proxy-managed/countries e GET /proxy-managed/cities e reutilize os
valores retornados nos campos proxy_managed_*.
curl --request POST \
--url https://api.wppfy.com/instance/connect \
--header 'Content-Type: application/json' \
--header 'token: <api-key>' \
--data '
{
"browser": "auto",
"systemName": "Minha Empresa",
"proxy_managed_country": "br",
"proxy_managed_state": "sp",
"proxy_managed_city": "campinas"
}
'{
"response": "Connecting",
"request_id": "5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f",
"status": {
"connected": false,
"loggedIn": false,
"jid": null
}
}Autorizações
Corpo
Número de telefone no formato internacional (ex: 5511999999999). Se informado, gera código de pareamento. Se omitido, gera QR code.
^\d{10,15}$"5511999999999"
Browser usado no ciclo de autenticação/conexão. auto preserva um perfil válido já salvo ou escolhe Safari, Firefox ou Edge para novas conexões.
auto, safari, firefox, edge, chrome "auto"
Sistema/nome exibido no celular em aparelhos conectados. Ajuda a identificar a instância no WhatsApp; para maior estabilidade, recomendamos deixar em branco e usar o valor padrão do navegador escolhido.
"Minha Empresa"
País desejado para o proxy regional, em ISO alpha-2 minúsculo. Use o valor retornado por GET /proxy-managed/countries.
^[a-z]{2}$"br"
Estado/subdivisão da cidade escolhida. Quando o país/cidade exigir desambiguação, use o campo state retornado por GET /proxy-managed/cities?country=br.
"sp"
Cidade escolhida para o proxy regional. Use sempre o campo value retornado por GET /proxy-managed/cities.
"campinas"
Dias de histórico pedidos ao celular no pareamento.
- Ausente: 90 dias, pelo histórico normal.
- De
1a90: os últimos N dias, pelo histórico normal. - De
91a365: os últimos N dias, pelo histórico completo. 0: o máximo, 365 dias pelo histórico completo.- Fora de 0–365: ignorado; valem os 90 dias.
Só vale em um pareamento novo. Uma instância já pareada reconecta sem pedir histórico, e um QR code ou código já gerado segue com o que foi pedido. O celular decide o que envia: os dias são um limite pedido, não uma garantia.
0 <= x <= 36590
Resposta
Sucesso
Estado atual da conexão
false
Estado do login
false
ID do WhatsApp (quando logado)
null
Detalhes completos da instância
Show child attributes
Show child attributes
{
"id": "i91011ijkl",
"token": "abc123xyz",
"status": "connected",
"paircode": "1234-5678",
"qrcode": "data:image/png;base64,iVBORw0KGg...",
"name": "Instância Principal",
"profileName": "Loja ABC",
"profilePicUrl": "https://example.com/profile.jpg",
"isBusiness": true,
"plataform": "Android",
"systemName": "WppFy",
"owner": "user@example.com",
"lastDisconnect": "2025-01-24T14:00:00Z",
"lastDisconnectReason": "Network error",
"adminField01": "custom_data",
"openai_apikey": "sk-...xyz",
"chatbot_enabled": true,
"chatbot_ignoreGroups": true,
"chatbot_stopConversation": "parar",
"chatbot_stopMinutes": 60,
"created": "2025-01-24T14:00:00Z",
"updated": "2025-01-24T14:30:00Z",
"currentPresence": "available"
}
Identificador da tentativa de pareamento e de seu histórico inicial. Opcional; é o mesmo informado nos eventos history e em GET /instance/history-sync/status.
"5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f"