PicChat

Contatos

Criar ou atualizar contato

POSThttps://api.picchat.com.br/contacts/create-or-update

Procura o contato da conta pelo celular e/ou e-mail (se os dois vierem, qualquer um dos dois casa) e atualiza o que existe ou cria um novo; new na resposta diz qual aconteceu. Na atualização, nome, sobrenome, e-mail e celular vazios ou ausentes mantêm o valor atual, mas status, is_marketing, font, font_detail, numberValid e emailValid enviados sempre sobrescrevem. Propriedades personalizadas vão como chaves no nível de cima do corpo ("etapa_do_funil": "lead"), pelo internal_name; para seleção, use o internal_name da opção, e valores que não casam com nenhuma opção são ignorados em silêncio. O campo properties (lista) é aceito pela validação mas não é processado: não use. Pegadinhas: sem celular nem e-mail, ou com e-mail mal formado, a API responde 500 sem detalhe; mobilephone precisa ir como texto (número dá 422). O escopo vem do token: account_id não precisa ser enviado e, se for, tem de ser o da própria conta.

Autenticação: Bearer tokenPermissão: Token da conta (Bearer). Estas rotas não passam pelo grupo de permissão do usuário.

Corpo da requisição (JSON)

Campos do corpo

  • first_namestring

    Nome. Em contato existente, vazio ou ausente mantém o valor atual.

  • last_namestring

    Sobrenome. Em contato existente, vazio ou ausente mantém o valor atual.

  • mobilephonestring

    Celular (texto, não número). A API remove tudo que não é dígito: até 11 dígitos sem começar por 55 recebe o DDI 55; começando por 55 com até 13 dígitos fica como está; mais de 13 dígitos é tratado como ID de grupo (`is_group` = true); qualquer outro formato é descartado. Só números brasileiros são normalizados corretamente.

  • emailstring (email)

    E-mail. É gravado em minúsculas e sem espaços; formato inválido derruba a requisição (500).

  • statusstring

    Status livre do contato. Enviado sempre sobrescreve.

  • is_marketingboolean

    Aceita comunicação de marketing.

  • fontstring

    Origem do contato. Valor fora da lista derruba a requisição com 500.

    referralsorganic_searchofflinesocial_mediapaid_searchpaid_socialemail_marketingother_campaignsdirect_trafficdirect_insertionimportation

  • font_detailstring

    Detalhe livre da origem (ex.: "formulario-site").

  • isGroupboolean

    Marca o contato como grupo. Só vale na criação; números com mais de 13 dígitos já viram grupo automaticamente.

  • numberValidboolean

    Marcação manual de número validado.

  • emailValidboolean

    Marcação manual de e-mail validado.

Respostas

201Contato criado ou atualizado. Traz o registro gravado, `new` e o eco das chaves extras enviadas.

  • idstring (uuid)

    ID do contato (UUID v7).

  • first_namestring | null

    Nome.

  • last_namestring | null

    Sobrenome.

  • statusstring | null

    Status livre do contato.

  • emailstring | null

    E-mail, sempre em minúsculas.

  • mobilephonestring | null

    Celular só com dígitos e DDI (ex.: 5511999990000), ou ID de grupo.

  • is_marketingboolean | null

    Aceita comunicação de marketing.

  • opt_outboolean | null

    Pediu para não receber mais mensagens.

  • is_groupboolean | null

    É um grupo de WhatsApp.

  • descriptionstring | null

    Descrição livre.

  • account_idstring (uuid)

    Conta dona do contato (a do token).

  • user_idstring (uuid) | null

    Usuário responsável; esta rota grava sempre null em contatos novos.

  • imagestring | null

    URL da foto.

  • font_detailstring | null

    Detalhe livre da origem (ex.: nome do formulário).

  • fontstring

    Origem do contato. Valor fora da lista derruba a requisição com 500.

    referralsorganic_searchofflinesocial_mediapaid_searchpaid_socialemail_marketingother_campaignsdirect_trafficdirect_insertionimportation

  • numberValidboolean | null

    Marcação de número validado (padrão false = "não validado", não "inválido").

  • invalid_numberboolean | null

    Número marcado como inválido pela plataforma.

  • invalid_emailboolean | null

    E-mail com bounce permanente.

  • emailValidboolean | null

    Marcação de e-mail validado (padrão false = "não validado").

  • deletedboolean | null

    Contato excluído.

  • is_verified_userboolean | null

    Usado por canais do Instagram.

  • follower_countinteger | null

    Usado por canais do Instagram.

  • userNamestring | null

    Usuário no Instagram.

  • is_user_follow_businessboolean | null

    Usado por canais do Instagram.

  • is_business_follow_userboolean | null

    Usado por canais do Instagram.

  • insta_idstring | null

    ID no Instagram.

  • wa_group_idstring | null

    ID do grupo na Cloud API (só grupos).

  • wa_invite_linkstring | null

    Link de convite do grupo (só grupos).

  • created_atstring (date-time)

    Criação.

  • updated_atstring (date-time)

    Última atualização.

  • newbooleanobrigatório

    true quando o contato foi criado nesta chamada; false quando um existente foi atualizado.

403Foi enviado um `account_id` (query ou corpo) diferente da conta do token.

422Falha de validação do corpo (class-validator). `message` é uma lista; `errorCode` aparece quando o primeiro item tem código catalogado.

498Token ausente, inválido, de conta inexistente ou revogado. Status não padrão (498), usado em toda a API.

500Sem `mobilephone` nem `email` válidos, e-mail mal formado ou `font` fora da lista. O motivo não vem no corpo.