LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Links de conexão

Usar com IA

Um link que o seu cliente abre para conectar o número de WhatsApp dele, sem receber o login do seu console. Um link por cliente seu, amarrado ao externalId que você escolheu.

Criar um link de conexão para o seu cliente

POST/v1/onboarding/links

Cria um link que o seu cliente abre para conectar o número de WhatsApp dele, sem receber o login do seu console.

Autenticação
Chave de API
Escopo exigido
onboarding:write

Corpo da requisição

application/json · obrigatório

  • externalIdstringopcional
    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 a 128 caracteres
  • displayNamestringopcional
    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 a 120 caracteres
  • redirectUrlstringopcional
    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.até 2048 caracteres · /^https:\/\/[^\s]+$/
  • numberIdstringopcional
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Respostas

201Criado.
  • idstring (uuid)obrigatório
  • urlstringobrigatório
    O endereço que você manda ao seu cliente. Ele contém o token, e o token aparece só nesta resposta.
  • expiresAtstringobrigatório
  • externalIdstring | nullobrigatório
  • redirectUrlstring | nullobrigatório
    A redirectUrl do pedido, ou nulo.
  • displayNamestring | nullobrigatório
    O nome do seu cliente que a página do link mostra, ou nulo.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Conta ainda sem liberação para conectarJSON
{
  "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"
  ]
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela 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."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
A conta já está na capacidade de númerosJSON
{
  "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
}
A autorização não admite reconexãoJSON
{
  "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"
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Criar vários links de conexão de uma vez

POST/v1/onboarding/links/batch

Cria até 100 links, cada item no mesmo formato de POST /v1/onboarding/links e com as mesmas regras, inclusive a capacidade do plano. Responde 200 com um resultado por item, com a url de cada link criado; um item que falha não derruba os outros.

Autenticação
Chave de API
Escopo exigido
onboarding:write

Corpo da requisição

application/json · obrigatório

  • linksarray<object>obrigatório
    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 a 100 itens
  • links[].externalIdstringopcional
    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 a 128 caracteres
  • links[].displayNamestringopcional
    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 a 120 caracteres
  • links[].redirectUrlstringopcional
    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.até 2048 caracteres · /^https:\/\/[^\s]+$/
  • links[].numberIdstringopcional
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Respostas

200Sucesso.
  • resultsarray<object>obrigatório
    Um resultado por item de links, na mesma ordem.
  • results[].indexintegerobrigatório
    A posição do item em links, a partir de 0.
  • results[].statusintegerobrigatório
    201 quando o link foi criado; senão o status do erro daquele item.
  • results[].linkobject | nullobrigatório
    O link criado, com a url (que aparece só aqui). Nulo quando houve erro.
  • results[].link.idstring (uuid)obrigatório
  • results[].link.urlstringobrigatório
    O endereço que você manda ao seu cliente. Ele contém o token, e o token aparece só nesta resposta.
  • results[].link.expiresAtstringobrigatório
  • results[].link.externalIdstring | nullobrigatório
  • results[].link.redirectUrlstring | nullobrigatório
    A redirectUrl do pedido, ou nulo.
  • results[].link.displayNamestring | nullobrigatório
    O nome do seu cliente que a página do link mostra, ou nulo.
  • results[].errorobject | nullobrigatório
    O erro deste item, no mesmo formato de erro da API. Nulo quando o link foi criado.
  • results[].error.errorstringobrigatório
  • results[].error.messagestringobrigatório
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Conta ainda sem liberação para conectarJSON
{
  "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"
  ]
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela 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."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Gerar de novo a url de um link de conexão

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

Gera um token novo para o mesmo link (mesmo id, mesmo rótulo, mesmo prazo): a url antiga deixa de funcionar na hora e a nova aparece só nesta resposta. Só vale para um link aberto; usado, vencido ou revogado responde 409. Use quando o seu cliente perdeu a url, em vez de revogar e criar outro.

Autenticação
Chave de API
Escopo exigido
onboarding:write

Parâmetros de caminho

  • idstring (uuid)obrigatório

Respostas

200Sucesso.
  • idstring (uuid)obrigatório
  • urlstringobrigatório
    O endereço que você manda ao seu cliente. Ele contém o token, e o token aparece só nesta resposta.
  • expiresAtstringobrigatório
  • externalIdstring | nullobrigatório
  • redirectUrlstring | nullobrigatório
    A redirectUrl do pedido, ou nulo.
  • displayNamestring | nullobrigatório
    O nome do seu cliente que a página do link mostra, ou nulo.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela 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."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
Link que não está abertoJSON
{
  "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"
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}