PicChat

Contatos

Listar contatos

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

Lista os contatos da conta (excluídos ficam de fora), paginados e ordenados por updated_at decrescente por padrão. Filtra por telefone ou e-mail exatos, lista, flags e por valor de propriedade (property.<internal_name>). Com include_properties=true cada contato traz properties (mapa) e properties_detail.

Autenticação: Bearer tokenPermissão: Contatos › 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.

  • searchstring

    Busca parcial, sem diferenciar maiúsculas, em nome, sobrenome, e-mail e usuário do Instagram; os dígitos do termo também são procurados no telefone.

  • mobilephonestring

    Telefone exato. Só os dígitos contam; DDI 55 é acrescentado quando o número tem até 11 dígitos (ex.: `11999990000` → `5511999990000`).

  • emailstring (email)

    E-mail exato, sem diferenciar maiúsculas.

  • list_idstring (uuid)

    Só contatos que estão nesta lista (vínculo não excluído).

  • opt_outboolean

    true = só quem pediu para não receber mensagens. Aceita `true`/`false` (também `1`/`0`, `yes`/`no`, `sim`/`nao`); outro valor é ignorado.

  • invalid_numberboolean

    true = só números marcados como inválidos. Aceita `true`/`false` (também `1`/`0`, `yes`/`no`, `sim`/`nao`); outro valor é ignorado.

  • is_groupboolean

    true = só grupos de WhatsApp. Aceita `true`/`false` (também `1`/`0`, `yes`/`no`, `sim`/`nao`); outro valor é ignorado.

  • statusstring

    Status do contato (igualdade exata).

  • 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.

  • property.{internal_name}string

    Filtro por propriedade: troque `{internal_name}` pelo nome interno da propriedade (ex.: `?property.cidade=São Paulo`). Casa o valor exato sem diferenciar maiúsculas; em propriedades de opção, aceita o nome ou o internal_name da opção. Pode repetir com propriedades diferentes (todas precisam casar). Valor vazio é ignorado.

  • include_propertiesboolean

    true = inclui `properties` e `properties_detail` em cada contato. Aceita `true`/`false` (também `1`/`0`, `yes`/`no`, `sim`/`nao`); outro valor é ignorado.

  • sortstringpadrão "updated_at"

    Campo de ordenação. Valor fora da lista usa `updated_at`.

  • orderstringpadrão "desc"

    Direção da ordenação por `sort`. Qualquer outro valor usa o padrão.

Respostas

200OK

  • itemsarray<ContactWithProperties>obrigatório

    Registros da página.

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

    ID do contato.

  • items[].first_namestring | nullobrigatório

    Nome.

  • items[].last_namestring | nullobrigatório

    Sobrenome.

  • items[].emailstring | nullobrigatório

    E-mail.

  • items[].mobilephonestring | nullobrigatório

    Telefone só com dígitos, com DDI (ex.: 5511999990000).

  • items[].statusstring | nullobrigatório

    Status livre do contato.

  • items[].is_marketingboolean | nullobrigatório

    Aceita comunicação de marketing.

  • items[].opt_outboolean | nullobrigatório

    Pediu para não receber mais mensagens.

  • items[].invalid_numberboolean | nullobrigatório

    Número marcado como inválido (sem WhatsApp ou rejeitado pela Meta).

  • items[].is_groupboolean | nullobrigatório

    É um grupo de WhatsApp.

  • items[].userNamestring | nullobrigatório

    Usuário do Instagram.

  • items[].fontstringobrigatório

    Fonte original do contato.

    referralsorganic_searchofflinesocial_mediapaid_searchpaid_socialemail_marketingother_campaignsdirect_trafficdirect_insertionimportation

  • items[].descriptionstring | nullobrigatório

    Descrição/observação.

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

    Criação.

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

    Última atualização.

  • items[].propertiesobjectobrigatório

    Mapa `internal_name → valor` das propriedades preenchidas.

  • items[].properties_detailarray<ContactPropertyValue>obrigatório

    Mesmas propriedades, com nome, tipo e data.

  • items[].properties_detail[].property_idstring (uuid)obrigatório

    ID da propriedade.

  • items[].properties_detail[].namestringobrigatório

    Nome da propriedade.

  • items[].properties_detail[].internal_namestringobrigatório

    Nome interno (chave usada em `properties` e no filtro `property.<internal_name>`).

  • items[].properties_detail[].typestring | nullobrigatório

    Tipo da propriedade (`internalName` do tipo: text, select, date...).

  • items[].properties_detail[].valuestring | nullobrigatório

    Valor. Para propriedades de opção (select), é o nome da opção.

  • items[].properties_detail[].option_internal_namestring | nullobrigatório

    internal_name da opção escolhida (só em select).

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

    Quando o valor foi gravado.

  • 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; `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.