Criar conexão
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.
Corpo da requisição
tenantIdstring · uuidobrigatórioIdentificador do projeto (tenantId) em que a conexão é criada. O projeto precisa ser de quem chama e estar ativo.
externalIdstringSeu 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 | nullUm 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órioURL 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.
proxy.countrystring | nullPaís de onde o proxy precisa sair, em ISO 3166-1 alfa-2 (por exemplo, BR). Omitido ou null: qualquer país.
Respostas
| Código | Erro e descrição |
|---|---|
| 200 | A 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. |
| 400 | O projeto está inativo (Tenant is inactive: …), ou a conexão não pôde ser iniciada; error diz por quê. |
| 400 | A 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. |
| 400 | FST_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. |
| 401 | Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}. |
| 402 | number_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. |
| 402 | subscription_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. |
| 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: o de outra pessoa responde exatamente como um que não existe. |
| 422 | A 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. |
| 429 | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de Retry-After.Cabeçalho: Retry-After |
| 501 | unsupported_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. |
| 503 | Com proxy: este gateway não consegue guardar URLs de proxy, porque nenhuma chave de criptografia está configurada. Nada é 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. 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