Cadastrar e atualizar contatos

Use POST /contacts/create-or-update para manter a base da PicChat em dia com o seu site, CRM ou formulário. Ele procura o contato pelo celular e/ou e-mail: se achar, atualiza; se não, cria. Por isso é seguro chamar sempre, sem consultar antes.

Criar ou atualizar

curl --request POST \
  --url https://api.picchat.com.br/contacts/create-or-update \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "Maria",
    "last_name": "Souza",
    "mobilephone": "5511999990000",
    "email": "maria.souza@example.com",
    "font": "organic_search",
    "font_detail": "formulario-site",
    "etapa_do_funil": "lead"
  }'

A resposta (201) traz o contato e o campo new: true quando foi criado, false quando já existia e foi atualizado.

Regras de atualização

• Precisa de celular ou e-mail (ou os dois). Se os dois vierem, qualquer um que casar identifica o contato.
• first_name, last_name, email e mobilephone vazios ou ausentes mantêm o valor atual.
• status, is_marketing, font, font_detail sempre sobrescrevem quando enviados — mande só se quiser trocar.
• mobilephone vai como texto, com DDI: "5511999990000". Número no JSON (sem aspas) é recusado com 422.

Origem do contato

font registra de onde o contato veio e aparece nos relatórios do painel:

Use font_detail para o detalhe livre (nome do formulário, campanha, página).

Propriedades personalizadas

Propriedades (etapa do funil, curso de interesse, cidade, plano…) vão como chaves no nível de cima do corpo, pelo internal_name da propriedade:

{
  "mobilephone": "5511999990000",
  "etapa_do_funil": "lead",
  "curso_interesse": "administracao",
  "cidade": "São Paulo"
}

• O internal_name de cada propriedade está no painel e em GET /v1/properties.
• Para propriedades de seleção, mande o internal_name da opção. Um valor que não bate com nenhuma opção é ignorado sem erro — confira as opções antes.

O corpo aceita um campo properties (lista), mas ele não é processado. Use sempre as chaves no nível de cima.

Buscar um contato

curl 'https://api.picchat.com.br/contacts/find?mobilephone=5511999990000&properties=etapa_do_funil' \
  --header 'Authorization: Bearer SEU_TOKEN'

Devolve o contato com as propriedades num mapa properties ({ "etapa_do_funil": "lead" }). Com properties=a,b vêm só as propriedades listadas.

Contato que não existe responde 200 com corpo vazio — não 404. Teste se o corpo veio vazio.

Para listar e filtrar contatos (por lista, propriedade, opt-out, data…), use GET /v1/contacts.

Erros comuns