LunaDocs

Loading search...

PortuguêsSign in to the console
On this page

Connection links

Use with AI

A link your customer opens to connect their WhatsApp number, without receiving your console login. One link per customer of yours, tied to the externalId you chose.

Create a connect link for your customer

POST/v1/onboarding/links

Creates a link your customer opens to connect their own WhatsApp number, without being given your console login.

Authentication
API key
Required scope
onboarding:write

Request body

application/json · required

  • externalIdstringoptional
    O seu identificador para este cliente, em texto livre de 1 a 128 caracteres. A Luna não o interpreta: ele volta como externalId no link e no número que resultar da conexão.1 to 128 characters
  • displayNamestringoptional
    O nome do seu cliente, em texto livre de 1 a 120 caracteres, que a página do link mostra ("Conectar o WhatsApp de ..."). Serve para o cliente reconhecer de quem é o pedido. É só texto da página: a janela da Meta que abre em seguida mostra o nome da Luna e não pode ser mudada.1 to 120 characters
  • redirectUrlstringoptional
    Para onde a página do link leva o seu cliente quando a conexão termina (https, até 2048 caracteres). A página acrescenta status (o estado final da conexão) e numberId (o número, quando a Luna já o registrou) na query. Ausente, o cliente fica na página da Luna.up to 2048 characters · /^https:\/\/[^\s]+$/
  • numberIdstringoptional
    O número a reconectar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Com ele, o link abre a reconexão daquele número em vez de uma conexão nova.1 to 64 characters · /^[A-Za-z0-9_-]+$/

Responses

201Created.
  • idstring (uuid)required
  • urlstringrequired
    O endereço que você manda ao seu cliente. Ele contém o token, e o token aparece só nesta resposta.
  • expiresAtstringrequired
  • externalIdstring | nullrequired
  • redirectUrlstring | nullrequired
    A redirectUrl do pedido, ou nulo.
  • displayNamestring | nullrequired
    O nome do seu cliente que a página do link mostra, ou nulo.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Account not yet released to connectJSON
{
  "error": "connection_not_released",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Esta conta ainda não pode conectar um número: falta confirmar o e-mail do cadastro. Abra o link que enviamos para esse e-mail e tente de novo. A lista faltando mostra o que ainda não foi cumprido.",
  "faltando": [
    "email_confirmado"
  ]
}
Free trial endedJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Account blocked by HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
409The request is well formed, but the resource state does not allow it. The error field says which case it is.
The account is already at its number capacityJSON
{
  "error": "number_capacity_reached",
  "message": "Esta conta já tem 20 números ativos, o máximo contratado (20). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.",
  "capacity": 20,
  "activeNumbers": 20
}
The authorization does not allow reconnectionJSON
{
  "error": "reconnect_not_applicable",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "A autorização deste número não admite reconexão.",
  "credentialStatus": "active"
}
415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
Content type not readJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Create several connect links at once

POST/v1/onboarding/links/batch

Creates up to 100 links, each item in the same shape as POST /v1/onboarding/links and under the same rules, plan capacity included. Answers 200 with one result per item, with the url of each created link; an item that fails does not bring the others down.

Authentication
API key
Required scope
onboarding:write

Request body

application/json · required

  • linksarray<object>required
    De 1 a 100 links, cada um no mesmo formato do corpo de POST /v1/onboarding/links: externalId, displayName, redirectUrl e numberId, todos opcionais.1 to 100 items
  • links[].externalIdstringoptional
    O seu identificador para este cliente, em texto livre de 1 a 128 caracteres. A Luna não o interpreta: ele volta como externalId no link e no número que resultar da conexão.1 to 128 characters
  • links[].displayNamestringoptional
    O nome do seu cliente, em texto livre de 1 a 120 caracteres, que a página do link mostra ("Conectar o WhatsApp de ..."). Serve para o cliente reconhecer de quem é o pedido. É só texto da página: a janela da Meta que abre em seguida mostra o nome da Luna e não pode ser mudada.1 to 120 characters
  • links[].redirectUrlstringoptional
    Para onde a página do link leva o seu cliente quando a conexão termina (https, até 2048 caracteres). A página acrescenta status (o estado final da conexão) e numberId (o número, quando a Luna já o registrou) na query. Ausente, o cliente fica na página da Luna.up to 2048 characters · /^https:\/\/[^\s]+$/
  • links[].numberIdstringoptional
    O número a reconectar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Com ele, o link abre a reconexão daquele número em vez de uma conexão nova.1 to 64 characters · /^[A-Za-z0-9_-]+$/

Responses

200Success.
  • resultsarray<object>required
    Um resultado por item de links, na mesma ordem.
  • results[].indexintegerrequired
    A posição do item em links, a partir de 0.
  • results[].statusintegerrequired
    201 quando o link foi criado; senão o status do erro daquele item.
  • results[].linkobject | nullrequired
    O link criado, com a url (que aparece só aqui). Nulo quando houve erro.
  • results[].link.idstring (uuid)required
  • results[].link.urlstringrequired
    O endereço que você manda ao seu cliente. Ele contém o token, e o token aparece só nesta resposta.
  • results[].link.expiresAtstringrequired
  • results[].link.externalIdstring | nullrequired
  • results[].link.redirectUrlstring | nullrequired
    A redirectUrl do pedido, ou nulo.
  • results[].link.displayNamestring | nullrequired
    O nome do seu cliente que a página do link mostra, ou nulo.
  • results[].errorobject | nullrequired
    O erro deste item, no mesmo formato de erro da API. Nulo quando o link foi criado.
  • results[].error.errorstringrequired
  • results[].error.messagestringrequired
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Account not yet released to connectJSON
{
  "error": "connection_not_released",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Esta conta ainda não pode conectar um número: falta confirmar o e-mail do cadastro. Abra o link que enviamos para esse e-mail e tente de novo. A lista faltando mostra o que ainda não foi cumprido.",
  "faltando": [
    "email_confirmado"
  ]
}
Free trial endedJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Account blocked by HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
Content type not readJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Generate the url of a connect link again

POST/v1/onboarding/links/{id}/reissue

Generates a new token for the same link (same id, label and expiry): the old url stops working at once and the new one appears only in this response. Only for an open link; used, expired or revoked answers 409. Use it when your customer lost the url, instead of revoking and creating another.

Authentication
API key
Required scope
onboarding:write

Path parameters

  • idstring (uuid)required

Responses

200Success.
  • idstring (uuid)required
  • urlstringrequired
    O endereço que você manda ao seu cliente. Ele contém o token, e o token aparece só nesta resposta.
  • expiresAtstringrequired
  • externalIdstring | nullrequired
  • redirectUrlstring | nullrequired
    A redirectUrl do pedido, ou nulo.
  • displayNamestring | nullrequired
    O nome do seu cliente que a página do link mostra, ou nulo.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Account blocked by HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409The request is well formed, but the resource state does not allow it. The error field says which case it is.
Link that is not openJSON
{
  "error": "link_not_open",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Só um link aberto pode ser reemitido, e este está usado. Crie um link novo com POST /v1/onboarding/links.",
  "status": "used"
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}