PicChat

Mensagens

Listar mensagens

GEThttps://api.picchat.com.br/v1/messages

Lista mensagens enviadas e recebidas da conta, paginadas. Por padrão ordena por created_at decrescente; com ticket_id ou contact_id o padrão passa a ser crescente (leitura de conversa). Usuário restrito a canais só vê mensagens desses canais.

Autenticação: Bearer tokenPermissão: Inbox › ver

Parâmetros de consulta (query)

  • pageintegerpadrão 1

    Página, começando em 1. Valor ausente, inválido ou menor que 1 vira 1.

  • limitintegerpadrão 20

    Itens por página. Padrão 20, máximo 100: acima disso é reduzido para 100 sem erro; valor inválido ou menor que 1 vira 20.

  • ticket_idstring (uuid)

    Só mensagens deste tíquete (muda a ordem padrão para `asc`).

  • contact_idstring (uuid)

    Só mensagens trocadas com este contato (muda a ordem padrão para `asc`).

  • channel_idstring (uuid)

    Só mensagens deste canal. Usuário com grupo de permissão e vinculado a canais só vê os desses canais; `channel_id` fora do escopo → 403 `channel_out_of_scope`.

  • automation_idstring (uuid)

    Só mensagens disparadas por esta automação.

  • template_idstring (uuid)

    Só mensagens que usaram este modelo.

  • typestring

    Tipo da mensagem.

  • statusstring

    Status de envio (`received` = recebida do contato).

  • from_meboolean

    true = enviadas pela conta; false = recebidas do contato. Aceita `true`/`false` (também `1`/`0`, `yes`/`no`, `sim`/`nao`); outro valor é ignorado.

  • searchstring

    Busca parcial no texto (`body`), sem diferenciar maiúsculas.

  • fromstring

    Início do período por `created_at` (inclusive), em ISO 8601 (`2026-09-01` ou `2026-09-01T03:00:00Z`). Só a data = 00:00 UTC. Valor inválido → 400.

  • tostring

    Fim do período por `created_at` (inclusive), em ISO 8601. Só a data inclui o dia inteiro (até 23:59:59.999 UTC). Valor inválido → 400.

  • orderstring

    Direção da ordenação por `created_at`. Padrão: `asc` quando há `ticket_id` ou `contact_id` (leitura cronológica), senão `desc`.

Respostas

200OK

  • itemsarray<Message>obrigatório

    Registros da página.

  • items[].idstring (uuid)obrigatório

    ID da mensagem.

  • items[].ticket_idstring (uuid) | nullobrigatório

    Tíquete da mensagem (null em disparos sem tíquete).

  • items[].contact_idstring (uuid) | nullobrigatório

    Contato da conversa.

  • items[].channel_idstring (uuid)obrigatório

    Canal por onde passou.

  • items[].automation_idstring (uuid) | nullobrigatório

    Automação que disparou a mensagem, se houver.

  • items[].template_idstring (uuid) | nullobrigatório

    Modelo usado, se houver.

  • items[].fromMeboolean | nullobrigatório

    true = enviada pela conta; false = recebida do contato.

  • items[].typestringobrigatório

    Tipo da mensagem.

    textimagevideoaudiodocumentlocationcontactsstickerinteractiveunsupportedtemplatebutton

  • items[].statusstringobrigatório

    Status de envio. Mensagens recebidas ficam como `received`.

    receivedpendingprocessingsendingcompletedcanceledpausederror

  • items[].bodystring | nullobrigatório

    Texto da mensagem.

  • items[].captionstring | nullobrigatório

    Legenda da mídia.

  • items[].filestring | nullobrigatório

    URL do arquivo de mídia.

  • items[].mime_typestring | nullobrigatório

    MIME type da mídia.

  • items[].latitudestring | nullobrigatório

    Latitude (mensagens de localização), como texto.

  • items[].longitudestring | nullobrigatório

    Longitude (mensagens de localização), como texto.

  • items[].vcardanyobrigatório

    Contatos compartilhados (JSON livre, pode ser null).

  • items[].contextanyobrigatório

    Contexto da mensagem (ex.: mensagem respondida) (JSON livre, pode ser null).

  • items[].reactionsanyobrigatório

    Reações recebidas (JSON livre, pode ser null).

  • items[].editedboolean | nullobrigatório

    Se a mensagem foi editada.

  • items[].errorstring | nullobrigatório

    Motivo do erro de envio.

  • items[].ex_idstring | nullobrigatório

    ID da mensagem no provedor (ex.: wamid da Meta).

  • items[].sent_atstring (date-time) | nullobrigatório

    Enviada ao provedor.

  • items[].delivery_atstring (date-time) | nullobrigatório

    Entregue.

  • items[].read_atstring (date-time) | nullobrigatório

    Lida.

  • items[].replied_atstring (date-time) | nullobrigatório

    Respondida pelo contato.

  • items[].error_atstring (date-time) | nullobrigatório

    Quando falhou.

  • items[].schedule_atstring (date-time) | nullobrigatório

    Agendada para.

  • items[].created_atstring (date-time)obrigatório

    Criação.

  • items[].usersobject | nullobrigatório

    Atendente que enviou (mensagens manuais).

  • items[].users.idstring (uuid)obrigatório

    ID do usuário.

  • items[].users.namestringobrigatório

    Nome.

  • items[].users.lastNamestring | nullobrigatório

    Sobrenome.

  • items[].contactsobject | nullobrigatório

    Contato da conversa.

  • items[].contacts.idstring (uuid)obrigatório

    ID do contato.

  • items[].contacts.first_namestring | nullobrigatório

    Nome.

  • items[].contacts.last_namestring | nullobrigatório

    Sobrenome.

  • items[].contacts.mobilephonestring | nullobrigatório

    Telefone só com dígitos, com DDI.

  • items[].messageParticipantobject | nullobrigatório

    Participante que escreveu, em conversas de grupo.

  • items[].messageParticipant.idstring (uuid)obrigatório

    ID do contato.

  • items[].messageParticipant.first_namestring | nullobrigatório

    Nome.

  • items[].messageParticipant.last_namestring | nullobrigatório

    Sobrenome.

  • items[].messageParticipant.mobilephonestring | nullobrigatório

    Telefone só com dígitos, com DDI.

  • items[].templatesobject | nullobrigatório

    Modelo usado.

  • items[].templates.idstring (uuid)obrigatório

    ID.

  • items[].templates.namestring | nullobrigatório

    Nome.

  • items[].automationsobject | nullobrigatório

    Automação de origem.

  • items[].automations.idstring (uuid)obrigatório

    ID.

  • items[].automations.namestring | nullobrigatório

    Nome.

  • totalintegerobrigatório

    Total de registros que casam com os filtros (todas as páginas).

  • pageintegerobrigatório

    Página devolvida (começa em 1).

  • limitintegerobrigatório

    Itens por página efetivamente usados (1–100).

  • pagesintegerobrigatório

    Total de páginas: `max(1, ceil(total / limit))`. Nunca é 0, mesmo sem resultados.

400Parâmetro de data (`from`, `to`, `updated_from`, `updated_to`) fora do formato ISO 8601.

403Acesso negado: usuário do token sem a permissão da rota (`permission_denied`) ou token não ligado a um usuário ativo (`token_without_user`) — para token de integração da conta isso só é aplicado quando `access.enforced` é true (veja GET /v1/me); token pessoal e JWT de sessão são sempre verificados; `channel_id` fora dos canais do usuário (`channel_out_of_scope`); `account_id` na query diferente da conta do token; conta do tipo INFRA.

498Token ausente, inválido, de outra finalidade (ex.: token do canal chat) ou revogado. Note o status não padrão 498.