Tipos de conexão
O campo provider é qr ou cloud_api. O que cada um pode fazer e onde os dois realmente diferem.
Toda conexão informa um provider, e ele tem um de dois valores:
provider | O que é | Como é integrado |
|---|---|---|
qr | Um número comum de WhatsApp (vendido como WAPP), pareado pela vinculação de um dispositivo. | POST /connections, depois escaneie um QR ou digite um código de pareamento. Totalmente self-service pela API — sem conta Meta Business. |
cloud_api | Um número de WhatsApp Business (vendido como WABA) registrado na Meta, na Cloud API oficial. | Embedded Signup da Meta, não esta API. |
Os dois tipos enviam e recebem pelos mesmos endpoints, com os mesmos corpos de requisição e os mesmos dois ids de mensagem. Se você achava que era impossível usar um QR a partir do seu próprio aplicativo: é possível.
Onde eles realmente diferem
Webhooks. Os eventos são disparados apenas para conexões qr. As conexões
cloud_api não emitem webhooks hoje — use GET /messages e
GET /connections/{id} para consultar esses dados.
Pareamento. POST /connections/{id}/pairing-code é um conceito de qr. Um
número cloud_api responde 409 not_supported_for_provider; essa é uma recusa
permanente, então não tente novamente.
Latência de envio. Um envio qr normalmente leva de 1 a 7 s (até ~20 s para
um texto longo) e pode levar ~2,5 minutos no caminho de autorrecuperação. Um
envio cloud_api leva cerca de 1 s. Dimensione o timeout HTTP para o caso mais
lento: no mínimo 180 s.
Marcar como lida. POST /messages/read marca o chat inteiro em uma conexão
qr. Uma conexão cloud_api só pode marcar uma mensagem específica, então uma
requisição apenas com phone resolve automaticamente a sua mensagem recebida
mais recente desse número.
Volume. Um número qr recém-pareado tem limites de aquecimento de 72 horas
no volume por hora; ultrapassar um deles retorna 429 warmup_limited. Veja
Licenças e teste.
Saúde da sessão. Uma conexão qr está vinculada a um telefone que precisa
continuar acessível, então ela pode cair e exigir um novo pareamento — é para
isso que servem connection.disconnected / connection.connected e a flag
needs_reconnect. Uma conexão cloud_api nunca escaneia nada e não tem esse
tipo de falha.
Providers desconhecidos não vazam
provider vira null em vez de repassar um valor não reconhecido. Se um novo
tipo de conexão for adicionado um dia, ele será citado aqui de propósito, então
ramificar por qr / cloud_api hoje é seguro — mas trate null como "um tipo
que este cliente não conhece" em vez de deixar o código quebrar.
Workspaces
Uma chave pertence a exatamente um workspace. O que isso significa para aplicativos multi-tenant e como um portal Bitrix24 difere de um workspace independente.
Licenças e teste
Um teste gratuito de 7 dias por número, depois uma licença mensal por número. O que é um slot e o que acontece quando um expira.