Projetos e conexões
Como organização, projeto e conexão se relacionam, o que você configura no projeto pela API e o ciclo de vida de um número: criar, desconectar, sair e excluir.
Tudo na apiwpp pertence a uma organização, a conta do painel. Dentro dela ficam os projetos (o tenant da API): cada projeto é um sistema seu, com o próprio endereço de webhook e as próprias chaves de API. Cada conexão é um número de WhatsApp de um projeto.
| Nível | Na API | O que guarda |
|---|---|---|
| Organização | organizationId | O plano, a assinatura e os números contratados, que valem para todos os projetos dela. |
| Projeto | tenant, tenantId | O webhook (endereço, token, cabeçalhos, segredo de assinatura), as chaves de API e as conexões. |
| Conexão | connection, connectionId | Um número de WhatsApp: a sessão, a fila de envio, os templates e o histórico. |
Uma chave de API pertence a um único projeto: ela só enxerga esse projeto e as conexões dele. Para trabalhar com outro projeto, crie uma chave nele (veja Autenticação).
Consultar o projeto
GET /tenants lista os projetos que a credencial alcança (com uma chave de API, o projeto dela), e GET /tenants/{id} devolve um projeto com o número de conexões. As duas pedem o escopo connections:read.
curl -s https://api.apiwpp.com/tenants/$TENANT_ID -H "Authorization: Bearer $API_KEY"{
"id": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
"organizationId": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
"name": "acme-crm",
"webhookBaseUrl": "https://crm.example.com/api/whatsapp/events",
"webhookHeaderNames": ["X-Crm-Account"],
"emitOutgoing": true,
"maxPerMinute": null,
"maxPerHour": null,
"maxPerDay": null,
"hasWebhookSecret": true,
"planId": "b7e2c9d4-1f3a-4c5b-8d6e-9f0a1b2c3d4e",
"subscriptionStatus": "active",
"trialEndsAt": null,
"currentPeriodEnd": "2026-10-24T12:00:00.000Z",
"isActive": true,
"createdAt": "2026-09-01T12:00:00.000Z",
"updatedAt": "2026-09-24T12:00:00.000Z",
"connectionCount": 1
}As credenciais do webhook nunca voltam na resposta: o token não aparece, o segredo vira hasWebhookSecret e dos cabeçalhos só vêm os nomes, em webhookHeaderNames. planId, subscriptionStatus, trialEndsAt e currentPeriodEnd são da organização, iguais em todos os projetos dela.
Configurar o webhook do projeto
PATCH /tenants/{id}, com o escopo webhooks:write, muda a configuração de webhook do projeto. Envie só os campos que quer mudar; a resposta é o projeto atualizado, no formato de GET /tenants/{id}.
| Campo | Tipo | Descrição |
|---|---|---|
webhookBaseUrl | string | O endereço que recebe os eventos. Conferido quando muda: https, sem usuário e senha na URL, e o host precisa resolver só para endereços públicos. Senão, 400. |
webhookToken | string | Enviado em toda entrega no cabeçalho X-Webhook-Token. Nunca é devolvido. |
webhookHeaders | objeto ou null | Cabeçalhos extras de toda entrega, de nome para valor. Substitui os anteriores; null remove todos. Só os nomes são devolvidos. |
webhookSecret | string ou null | O segredo da assinatura HMAC (X-Sales-Signature). null ou "" desliga a assinatura. Nunca é devolvido. |
emitOutgoing | boolean | Ativa o evento message.outgoing para as mensagens que o número envia. |
A mudança vale para as próximas entregas de todas as conexões do projeto.
curl -s -X PATCH https://api.apiwpp.com/tenants/$TENANT_ID \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"webhookBaseUrl": "https://crm.example.com/api/whatsapp/events", "emitOutgoing": true}'const res = await fetch(`https://api.apiwpp.com/tenants/${tenantId}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
webhookBaseUrl: 'https://crm.example.com/api/whatsapp/events',
emitOutgoing: true,
}),
})
const tenant = await res.json()
if (!res.ok) throw new Error(`${res.status}: ${tenant.error}`)
console.log(tenant.hasWebhookSecret, tenant.webhookHeaderNames)Antes de trocar o endereço, teste o novo com POST /tenants/webhook-test: ele envia um evento ping assinado, com as mesmas regras e o mesmo limite de 10 segundos das entregas reais, e não salva nada. Com o tenantId, a assinatura usa o segredo guardado do projeto; o token e os cabeçalhos guardados só são reaproveitados se o webhookBaseUrl for o mesmo que está salvo, e para outro endereço o webhookToken é obrigatório.
curl -s -X POST https://api.apiwpp.com/tenants/webhook-test \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"webhookBaseUrl": "https://crm.example.com/api/whatsapp/events", "webhookToken": "'$WEBHOOK_TOKEN'", "tenantId": "'$TENANT_ID'"}'{ "ok": true, "status": 200, "latencyMs": 184, "error": null }O guia Webhooks e assinatura mostra como o seu servidor confere a assinatura e o que acontece quando ele não responde.
Desativar o projeto
DELETE /tenants/{id}, com o escopo connections:write, desativa o projeto e responde { "deleted": true }. Nada é apagado: as conexões são desconectadas com as sessões preservadas.
Um projeto inativo:
- não recebe webhooks;
- não aparece nas conexões de
GET /connections; - não aceita chaves de API: todas as chaves do projeto passam a responder
401, inclusive a que fez a chamada, e criar uma chave nele responde409.
Criar uma conexão
Há dois caminhos para criar uma conexão, ambos com o escopo connections:write:
POST /connections, com o projeto no corpo (tenantId, obrigatório), responde só{ connectionId, externalId }.POST /tenants/{id}/connections, com o projeto no caminho, responde a conexão completa, comoGET /tenants/{id}/connectionsa lista.
Os dois aceitam externalId, o seu identificador para o número (por exemplo, o id do cliente no seu sistema). Se o projeto já tem uma conexão com esse externalId, a API conecta essa em vez de criar outra, e ela não ocupa mais um número. O externalId volta no envelope de todos os eventos da conexão. Os dois aceitam também um proxy opcional, conferido antes de a conexão ser criada (veja Proxy e IP dedicado).
curl -s -X POST https://api.apiwpp.com/connections \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"tenantId": "'$TENANT_ID'", "externalId": "shop-42"}'const res = await fetch('https://api.apiwpp.com/connections', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ tenantId, externalId: 'shop-42' }),
})
const body = await res.json()
if (res.status === 402 && body.code === 'number_limit_reached') {
// Todos os números contratados estão em uso: exclua uma conexão ou contrate mais
} else if (!res.ok) {
throw new Error(`${res.status}: ${body.error}`)
}
const { connectionId } = body{ "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f", "externalId": "shop-42" }A conexão nasce aguardando o pareamento: siga com o QR code ou com o código de pareamento, em Parear um número.
Números contratados. Cada conexão ocupa um dos números que a organização contratou, somando todos os projetos, qualquer que seja o status dela, até ser excluída. Desconectar ou sair do WhatsApp não libera o número. Além do contratado, a resposta é 402 com code: number_limit_reached.
| Status | code | Quando |
|---|---|---|
400 | — | Falta o tenantId, a verificação do proxy recusou a URL, ou a conexão não pôde ser iniciada. |
402 | number_limit_reached | Todos os números contratados estão em uso. |
402 | subscription_inactive | O teste acabou ou uma fatura venceu e passou da carência. |
404 | — | O projeto não existe ou não é seu. |
422 | — | A verificação através do proxy falhou; nada foi criado. |
501 | unsupported_by_provider | O provedor da conexão não oferece a operação (vem no campo error). |
503 | — | A conexão está mudando de instância (com Retry-After), ou o servidor não pode guardar URLs de proxy. |
Listar e consultar conexões
GET /connectionslista as conexões dos projetos ativos da credencial, das mais novas para as mais antigas, com o status atual em minúsculas (open,close…). As conexõesfailedficam de fora, a menos que você passeincludeFailed=true.GET /tenants/{id}/connectionslista as conexões de um projeto, com o status gravado, em maiúsculas (OPEN,CLOSE…).GET /tenants/{id}/connections/{connId}devolve uma conexão com os 50 eventos mais recentes dela (CONNECTED,DISCONNECTED,LOGGED_OUTe outros; os heartbeats bem-sucedidos ficam de fora), do mais novo para o mais antigo. É o primeiro lugar para entender por que um número caiu.
Todas pedem o escopo connections:read. Os status possíveis de uma conexão e o que fazer em cada um estão em Parear um número.
Histórico de heartbeats
A apiwpp confere periodicamente se cada conexão aberta está viva. GET /tenants/{id}/connections/{connId}/heartbeats devolve esse histórico em intervalos de meia hora alinhados ao relógio, do mais antigo ao atual (parcial). O parâmetro hours, de 1 a 168 (padrão 24), escolhe o período.
curl -s "https://api.apiwpp.com/tenants/$TENANT_ID/connections/$CONNECTION_ID/heartbeats?hours=48" \
-H "Authorization: Bearer $API_KEY"{
"buckets": [
{ "start": "2026-09-24T11:00:00.000Z", "ok": true },
{ "start": "2026-09-24T11:30:00.000Z", "ok": false },
{ "start": "2026-09-24T12:00:00.000Z", "ok": null }
],
"uptimePct": 50
}Em cada intervalo, ok é false se algum heartbeat falhou, true se só houve sucessos e null sem dados. uptimePct é a porcentagem de intervalos true entre os que têm dados, com uma casa decimal, ou null quando nenhum tem.
Desconectar, reconectar, sair e excluir
| Ação | Operação | A sessão | O número contratado |
|---|---|---|---|
| Desconectar | POST /connections/{id}/disconnect ou POST /tenants/{id}/connections/{connId}/disconnect | Preservada | Continua ocupado |
| Reconectar | POST /tenants/{id}/connections/{connId}/connect | Usada, se existir | Continua ocupado |
| Sair do WhatsApp | POST /connections/{id}/logout | Apagada | Continua ocupado |
| Excluir | DELETE /tenants/{id}/connections/{connId} | Apagada, com a conexão | Liberado |
Todas pedem o escopo connections:write e respondem { "ok": true }.
- Desconectar fecha a conexão com o WhatsApp e guarda a sessão: o número continua vinculado ao celular e volta sem QR code.
- Reconectar inicia de novo uma conexão fechada. Com sessão, ela reconecta; sem sessão (depois de sair do WhatsApp), começa um pareamento novo, e o QR code aparece em
GET /connections/{id}/qr. Responde402comsubscription_inactivese a organização não está em dia, e500se a conexão não pôde ser iniciada. - Sair do WhatsApp remove o aparelho vinculado do celular e apaga a sessão. Use para trocar o número de uma conexão: saia, reconecte e pareie o número novo. Responde
404se a conexão não existe ou se o logout falhou. - Excluir faz o logout e apaga a conexão com a sessão, os templates e o histórico. Se o logout falha, nada é apagado e a resposta é
409: tente de novo.
Desconectar, sair e excluir funcionam mesmo com a organização sem pagamento em dia, para que você sempre consiga liberar um número. As operações que usam a sessão do WhatsApp respondem 503 com Retry-After enquanto a conexão muda de instância: repita depois do tempo indicado.
Próximos passos
- Parear um número: QR code, código de pareamento e os status da conexão.
- Webhooks e assinatura: receber os eventos e conferir a assinatura.
- Autenticação: as chaves de API de cada projeto e os escopos.
- Referência: Projetos: os parâmetros e as respostas de cada operação.