Pular para o conteúdo

Criar conexão

POST/connections

Cria uma conexão de WhatsApp num projeto e devolve o connectionId para parear um número com o QR code ou com o código de pareamento. Se o projeto já tem uma conexão com o mesmo externalId, nada é criado: essa conexão é conectada de novo e o connectionId dela volta. Escopo necessário: connections:write.

Ver em Markdown

Corpo da requisição

tenantIdstring · uuidobrigatório

Identificador do projeto (tenantId) em que a conexão é criada. O projeto precisa ser de quem chama e estar ativo.

externalIdstring

Seu identificador para a conexão (por exemplo, o id da loja ou do cliente no seu sistema). Volta como externalId no envelope de todos os webhooks da conexão. Se o projeto já tem uma conexão com esse externalId, ela é conectada de novo em vez de uma nova ser criada.

proxyobject | null

Um proxy seu para a conexão, no mesmo formato de PUT /connections/{id}/proxy: o socket do WhatsApp e os uploads e downloads de mídia dela saem por ele desde o primeiro socket. Omitido ou null: sem proxy próprio.

proxy.urlstringobrigatório

URL do proxy: socks5://, socks5h:// (nos dois, é o proxy que resolve os nomes de host), http:// ou https:// (os dois últimos por HTTP CONNECT), com usuario:senha@ opcional. Só esquema, credenciais, host e porta, sem caminho, query ou fragmento; o host precisa ser público. É gravada criptografada e nunca volta em nenhuma resposta.

de 1 a 2048 caracteres
proxy.countrystring | null

País de onde o proxy precisa sair, em ISO 3166-1 alfa-2 (por exemplo, BR). Omitido ou null: qualquer país.

formato `^[A-Za-z]{2}$`

Respostas

Respostas: código de status, erro e descrição
CódigoErro e descrição
200A conexão foi criada (ou a do externalId foi conectada de novo). Traz connectionId e externalId; pareie com o QR code ou com o código de pareamento.
400O projeto está inativo (Tenant is inactive: …), ou a conexão não pôde ser iniciada; error diz por quê.
400A URL do proxy não é aceita: não é uma URL, o esquema não é socks5, socks5h, http ou https, tem caminho, query ou fragmento, tem senha sem usuário, o host não é público, ou country não tem duas letras.
400FST_ERR_VALIDATIONA requisição não segue o schema da operação (por exemplo, um id que não é um UUID); message diz o que está errado.
401Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}.
402number_limit_reachedA organização já tem todos os números que contratou (The organization holds its N number(s)…): exclua uma conexão ou contrate mais números.
402subscription_inactiveA organização dona da conexão não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. Pague para voltar a usar.
403A chave não tem o escopo connections:write; a mensagem de erro cita o escopo que falta.
404O projeto não existe ou não é de quem chama: o de outra pessoa responde exatamente como um que não existe.
422A verificação pelo proxy falhou, e a mensagem diz só como: o proxy não foi alcançado ou não alcançou o serviço que informa o IP de saída (the proxy could not be reached…, inclusive por tempo esgotado), recusou as credenciais (the proxy refused the credentials), não disse de onde sai (the IP echo endpoint did not tell where the proxy exits) ou sai em outro país que não o de country.
429Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de Retry-After.Cabeçalho: Retry-After
501unsupported_by_providerO provedor da conexão não faz esta operação: por exemplo, a conexão que o externalId indica roda num provedor que não usa proxy, e o corpo trouxe um proxy.
503Com proxy: este gateway não consegue guardar URLs de proxy, porque nenhuma chave de criptografia está configurada. Nada é criado.
503A instância do gateway que roda a conexão está mudando (um reinício, um failover) ou não responde: espere os segundos de Retry-After e tente de novo.

Detalhes

Cada conexão ocupa um dos números que a organização do projeto contratou, até ser excluída. Passando disso, a resposta é 402 com code: number_limit_reached; conectar de novo a conexão que um externalId indica não ocupa outro número.

Com proxy, o proxy é verificado antes de qualquer coisa ser criada (400, 422 ou 503 quando recusado, e nada é criado) e gravado antes do primeiro socket: nem o primeiro QR code sai por fora dele. Com o externalId de uma conexão que já existe, o proxy dela é trocado, e um socket ativo se reconecta por ele. Veja Proxy e IP dedicado.

Depois de criar, mostre o QR code com GET /connections/{id}/qr ou peça um código com POST /connections/{id}/pairing-code. O webhook connection.status com status: open avisa quando o número foi pareado.

POST /tenants/{id}/connections faz o mesmo com o projeto no caminho (veja Criar conexão no projeto).

Guia: Parear um número

Esta página ajudou? · Atualizado em 28 set 2026