Pular para o conteúdo
GET/conversas

Listar conversas

conversas:lerpaginada

Da mais recente para a mais antiga, paginado por cursor.

GET /conversas

curl "https://chat.forsi.com.br/api/v1/conversas?estado=aberta&limite=20" \
  -H "Authorization: Bearer $FORSI_CHAVE"
Resposta 200
{
  "dados": [
    {
      "id": "495a7cae-128c-4b66-adbc-807b3959c129",
      "caixa_id": "7a9d53e9-9d1b-4122-923b-fac67958f445",
      "grupo": false,
      "titulo": "Consulta de retorno",
      "estado": "aberta",
      "responsavel_id": "42b8028f-d7ce-4706-9567-44ac3bff4219",
      "equipe_id": "55174f08-dda3-49e6-bc5d-9309becdaf6d",
      "agente_id": "d1ab0f6b-41bf-4522-baaa-c3e281a79935",
      "etiquetas": ["ea287b0d-9968-4022-b9c7-b6dc239e6101"],
      "nao_lidas": 2,
      "janela_ate": "2026-10-04T13:05:12.481Z",
      "ultima_mensagem_em": "2026-10-04T13:05:12.481Z",
      "ultima_previa": "Oi, queria remarcar minha consulta",
      "ultima_direcao": "texto",
      "criado_em": "2026-10-04T13:05:12.481Z",
      "atualizado_em": "2026-10-04T13:05:12.481Z",
      "resolvida_em": "2026-10-04T13:05:12.481Z",
      "contato": {
        "id": "08054a7f-a752-481e-9915-cf4cf944df39",
        "nome": "Maria Souza",
        "telefone": "+5531988887777"
      },
      "origem_anuncio": {
        "anuncio_id": "texto",
        "titulo": "Consulta de retorno",
        "canal": "whatsapp",
        "clicado_em": "2026-10-04T13:05:12.481Z"
      }
    }
  ],
  "proximo": "1791205512481_3791c08d-72dd-4002-89ff-1e14a11c07e5"
}

Parâmetros de consulta#

  • estado"aberta" | "pendente" | "adiada" | "resolvida"opcional
    —
  • caixa_iduuidopcional
    —
  • contato_iduuidopcional
    —
  • telefonestringopcional

    Com DDI e DDD. Acha o contato com ou sem o 9º dígito.

    • mín. 8 caracteres
    • até 30 caracteres
    • ex.: +55 31 98888-7777
  • desdedata e hora ISO 8601opcional

    Só conversas atualizadas a partir desta data (ISO 8601).

  • anunciostringopcional

    Só conversas que vieram de anúncio: 1 para qualquer anúncio ou o id de um anúncio.

  • limiteintegeropcional

    Itens por página (1 a 100, padrão 50).

  • cursorstringopcional

    Valor de proximo da página anterior.

    • até 80 caracteres

Resposta#

200 com {"dados": ...}: uma lista de Conversa, paginada por cursor (como paginar).

  • iduuidopcional
    —
  • caixa_iduuidopcional
    —
  • grupobooleanopcional
    —
  • titulostring ou nullopcional
    —
  • estado"aberta" | "pendente" | "adiada" | "resolvida"opcional
    —
  • responsavel_iduuid ou nullopcional
    —
  • equipe_iduuid ou nullopcional
    —
  • agente_iduuid ou nullopcional
    —
  • etiquetaslista de uuidopcional
    —
  • nao_lidasintegeropcional
    —
  • janela_atedata e hora ISO 8601 ou nullopcional

    Até quando a janela de 24 h da API oficial está aberta.

  • ultima_mensagem_emdata e hora ISO 8601 ou nullopcional
    —
  • ultima_previastring ou nullopcional
    —
  • ultima_direcaostring ou nullopcional
    —
  • criado_emdata e hora ISO 8601opcional
    —
  • atualizado_emdata e hora ISO 8601opcional
    —
  • resolvida_emdata e hora ISO 8601 ou nullopcional
    —
  • contatoobject ou nullopcional
    —
  • contato.iduuidopcional
    —
  • contato.nomestring ou nullopcional
    —
  • contato.telefonestring ou nullopcional
    —
  • origem_anuncioobject ou nullopcional

    Primeiro anúncio que levou a pessoa ao WhatsApp, Instagram ou Messenger.

  • origem_anuncio.anuncio_idstring ou nullopcional
    —
  • origem_anuncio.titulostring ou nullopcional
    —
  • origem_anuncio.canalstringopcional
    —
  • origem_anuncio.clicado_emdata e hora ISO 8601opcional
    —

Erros#

Todo erro vem como {"erro": {"codigo", "mensagem"}}. Trate pelo codigo: ele não muda.

Status de erro desta operação
StatusQuando
401Chave ausente ou inválida (resposta igual para qualquer motivo).
403Plano sem API, escopo insuficiente ou https/origem recusados.
422Dados inválidos ou regra de negócio (ex.: janela_fechada; conta_restrita = a Meta restringiu a conta por spam: erro traz os campos de RestricaoMeta, como ate, escopo, motivo e retry_after_s).
429Limite de requisições. Veja Retry-After.
Códigos de erro que esta área pode devolver2
  • conversa_inexistenteConversa não encontrada.
  • cursor_invalidoCursor inválido. Use o valor de "proximo" da página anterior.

Os erros que valem para qualquer rota (chave, limite, JSON) estão em Erros.