LunaDocs

Loading search...

PortuguêsSign in to the console
On this page

Conversations

Use with AI

One row per contact per number, with the state of the 24 hour customer service window.

List conversations

GET/v1/conversations

One row per correspondent per number, from the most active to the most idle.

Authentication
API key
Required scope
messages:read

Query parameters

  • limitintegeroptional
    minimum 1 · maximum 100
  • phoneNumberIdstringoptional
    O número: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • externalIdstringoptional
    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 to 128 characters
  • waIdstringoptional
    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 to 64 characters
  • userIdstringoptional
    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 to 200 characters
  • cursorstringoptional
    up to 256 characters

Responses

200Success.
  • dataarray<object>required
  • data[].idstring (uuid)required
  • data[].waIdstring | nullrequired
    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 | nullrequired
    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 | nullrequired
    O BSUID pai do interlocutor, quando a Meta o manda. Nulo no demais.
  • data[].usernamestring | nullrequired
    O nome de usuário do interlocutor, quando ele adotou um. Nulo no demais.
  • data[].phoneNumberIdstringrequired
  • data[].numberIdstring (uuid)required
    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 | nullrequired
    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 | nullrequired
    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 | nullrequired
  • data[].createdAtstringrequired
  • data[].lastMessageobject | nullrequired
  • data[].lastMessage.directionstringrequired
  • data[].lastMessage.typestring | nullrequired
  • data[].lastMessage.bodyTextstring | nullrequired
  • data[].lastMessage.createdAtstringrequired
  • data[].windowOpenbooleanrequired
    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 | nullrequired
    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 | nullrequired
    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 | nullrequired
    Mande este valor de volta em cursor para pegar a próxima página. Nulo significa fim.
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"
}
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."
}
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."
}