LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Conversas

Usar com IA

Uma linha por interlocutor por número, com o estado da janela de atendimento de 24 horas.

Listar conversas

GET/v1/conversations

Uma linha por interlocutor por número, da mais ativa para a mais parada.

Autenticação
Chave de API
Escopo exigido
messages:read

Parâmetros de consulta

  • limitintegeropcional
    mínimo 1 · máximo 100
  • phoneNumberIdstringopcional
    O número: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • externalIdstringopcional
    O rótulo que você deu ao seu cliente (externalId): só as conversas dos números dele. Igualdade exata; um rótulo sem número devolve lista vazia.1 a 128 caracteres
  • waIdstringopcional
    O identificador do interlocutor no WhatsApp (o waId da conversa, em geral o telefone só com dígitos): só as conversas dele, em cada número. Igualdade exata, mas o celular brasileiro vale nas duas grafias, com e sem o 9 depois do DDD (a Meta entrega alguns sem ele); um waId sem conversa devolve lista vazia.1 a 64 caracteres
  • userIdstringopcional
    O BSUID do interlocutor (userId), o identificador do usuário que não depende do telefone: só a conversa dele, em cada número. Igualdade exata; um userId sem conversa devolve lista vazia.1 a 200 caracteres
  • cursorstringopcional
    até 256 caracteres

Respostas

200Sucesso.
  • dataarray<object>obrigatório
  • data[].idstring (uuid)obrigatório
  • data[].waIdstring | nullobrigatório
    O telefone do interlocutor (wa_id da Meta), cru. Nulo quando o interlocutor escreveu só com BSUID, caso em que userId o identifica. Mudou de obrigatório para anulável com o BSUID: quem lia como texto sempre presente precisa tratar o nulo.
  • data[].userIdstring | nullobrigatório
    O BSUID do interlocutor, como a Meta o mandou (por exemplo US.13491208655302741918). Nulo quando a Meta nunca o mandou para esta conversa, como nas conversas anteriores ao BSUID que ainda não receberam mensagem com ele.
  • data[].parentUserIdstring | nullobrigatório
    O BSUID pai do interlocutor, quando a Meta o manda. Nulo no demais.
  • data[].usernamestring | nullobrigatório
    O nome de usuário do interlocutor, quando ele adotou um. Nulo no demais.
  • data[].phoneNumberIdstringobrigatório
  • data[].numberIdstring (uuid)obrigatório
    O número da Luna a que a conversa pertence, o mesmo id de GET /v1/numbers. É o mesmo valor de phoneNumberId, com o nome que o resto da API usa.
  • data[].externalIdstring | nullobrigatório
    O externalId do número da conversa, o rótulo que você deu ao seu cliente. Nulo quando o número não tem.
  • data[].contactNamestring | nullobrigatório
    O nome que o interlocutor exibe no WhatsApp, como a Meta o mandou na última mensagem recebida que trouxe um. Nulo quando ele nunca mandou o nome, ou quando a conversa não tem mensagem recebida guardada.
  • data[].displayNumberstring | nullobrigatório
  • data[].createdAtstringobrigatório
  • data[].lastMessageobject | nullobrigatório
  • data[].lastMessage.directionstringobrigatório
  • data[].lastMessage.typestring | nullobrigatório
  • data[].lastMessage.bodyTextstring | nullobrigatório
  • data[].lastMessage.createdAtstringobrigatório
  • data[].windowOpenbooleanobrigatório
    Verdadeiro quando você pode mandar mensagem livre para este interlocutor agora. Falso significa que o caminho é enviar um template, e a mensagem livre volta a ser aceita quando o contato responder.
  • data[].windowExpiresAtstring | nullobrigatório
    Instante em que a janela de atendimento fecha, em ISO-8601. Nulo quando não há janela conhecida, e nesse caso windowOpen é falso.
  • data[].windowSourcestring | nullobrigatório
    O que abriu a janela: usuario quando o interlocutor escreveu, anuncio quando ele veio de um anúncio ou botão de página, e desconhecido quando a origem não foi identificada. O valor template existe no vocabulário e não é mais gravado: enviar um template não abre a janela. Nulo quando não há janela conhecida.
  • nextCursorstring | nullobrigatório
    Mande este valor de volta em cursor para pegar a próxima página. Nulo significa fim.
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"
}
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."
}
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."
}