Pular para o conteúdo

Criar conexão no projeto

POST/tenants/{id}/connections

Como POST /connections, para o projeto do caminho: cria uma conexão de WhatsApp e já inicia o pareamento. Se o externalId já indica uma conexão do projeto, conecta essa em vez de criar outra. A resposta é a conexão no formato de GET /tenants/{id}/connections (sem tenantName, com status em minúsculas). Escopo necessário: connections:write.

Ver em Markdown

Parâmetros de caminho

idstring · uuidobrigatório

Identificador do projeto (tenantId).

Corpo da requisição

externalIdstring

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

proxyobject | null

Proxy próprio da conexão, no mesmo formato de PUT /connections/{id}/proxy: o socket e os envios e downloads de mídia saem por ele desde o primeiro.

proxy.urlstringobrigatório

URL do proxy: socks5:// ou socks5h:// (nos dois, o proxy resolve os nomes), http:// ou https:// (HTTP CONNECT), com usuário:senha@ opcional; só esquema, credenciais, host e porta. Só de escrita: as respostas nunca trazem a URL nem as credenciais.

de 1 a 2048 caracteres
proxy.countrystring | null

País por onde o proxy precisa sair (ISO 3166-1 alfa-2, como BR), conferido antes do pareamento; ausente 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 criada (ou a que o externalId indica), com status pending até o número ser pareado.
400A proxy.url é inválida (esquema diferente de socks5, socks5h, http ou https, com caminho, longa demais, ou com um host que resolve para um endereço não público), ou proxy.country não é um código de duas letras. Nada foi criado.
400A conexão não pôde ser iniciada: por exemplo, o projeto está inativo (Tenant is inactive). error diz o motivo.
400FST_ERR_VALIDATIONO corpo não segue o schema da operação, ou id não é um UUID; message diz o que está errado.
401Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. A chave de um projeto desativado também responde 401.
402subscription_inactiveA organização dona do projeto não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. O corpo traz error e code; regularize a assinatura no painel.
402number_limit_reachedA organização já usa todos os números que contratou: exclua uma conexão ou contrate mais números. O corpo traz error e code.
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 (Tenant not found): uma chave de API alcança só o próprio projeto, e o de outra pessoa responde igual a um que não existe.
422A verificação pelo proxy falhou: ele não conectou, ou saiu por um país diferente de proxy.country. Nada foi criado.
429Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de Retry-After. Veja Limites.Cabeçalho: Retry-After
500A conexão foi iniciada, mas não foi encontrada no banco logo depois (Connection created but not persisted). Repita com o mesmo externalId: se a conexão existir, ela é conectada em vez de uma nova ser criada.
501unsupported_by_providerO provedor da conexão não aceita isso: por exemplo, um proxy para a conexão que o externalId indica, quando ela roda num provedor que não mantém uma sessão própria.
503Este gateway não pode guardar URLs de proxy, porque não há uma chave de criptografia configurada. Nada foi 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: além deles, 402 number_limit_reached. Conectar a conexão que um externalId indica não ocupa outro número.

Com proxy, ele é verificado antes de qualquer coisa (400, 422 ou 503 quando recusado, e nada é criado) e gravado antes do primeiro socket: nem o primeiro QR code sai por fora dele. Veja Proxy e IP dedicado.

Depois, pareie o número com o QR code de GET /tenants/{id}/connections/{connId}/qr ou com o código de POST /connections/{id}/pairing-code. Veja Parear um número.

Guia: Projetos e conexões

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