Criar conexão no projeto
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.
Parâmetros de caminho
idstring · uuidobrigatórioIdentificador do projeto (tenantId).
Corpo da requisição
externalIdstringSeu 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 | nullProxy 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órioURL 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.
proxy.countrystring | nullPaís por onde o proxy precisa sair (ISO 3166-1 alfa-2, como BR), conferido antes do pareamento; ausente ou null: qualquer país.
Respostas
| Código | Erro e descrição |
|---|---|
| 200 | A conexão criada (ou a que o externalId indica), com status pending até o número ser pareado. |
| 400 | A 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. |
| 400 | A conexão não pôde ser iniciada: por exemplo, o projeto está inativo (Tenant is inactive). error diz o motivo. |
| 400 | FST_ERR_VALIDATIONO corpo não segue o schema da operação, ou id não é um UUID; message diz o que está errado. |
| 401 | Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. A chave de um projeto desativado também responde 401. |
| 402 | subscription_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. |
| 402 | number_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. |
| 403 | A chave não tem o escopo connections:write; a mensagem de erro cita o escopo que falta. |
| 404 | O 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. |
| 422 | A verificação pelo proxy falhou: ele não conectou, ou saiu por um país diferente de proxy.country. Nada foi criado. |
| 429 | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de Retry-After. Veja Limites.Cabeçalho: Retry-After |
| 500 | A 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. |
| 501 | unsupported_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. |
| 503 | Este gateway não pode guardar URLs de proxy, porque não há uma chave de criptografia configurada. Nada foi criado. |
| 503 | A 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