Contatos pela API: criar, buscar, editar e etiquetar

Rotas

Passo a passo: criar ou encontrar um contato

1. Envie os dados que você tem. Informe ao menos um identificador: telefone, e-mail ou identidade de canal.

curl -s -X POST https://http.pipebr.app/v1/contacts \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Exemplo",
    "phoneE164": "+5511955550101",
    "email": "maria@exemplo.test",
    "atributos": { "plano": "ouro", "cliente_desde": "2024" }
  }'

1. A resposta é 201 se o contato foi criado e 200 se já existia. O campo created diz qual foi:

{
  "id": "b3a1c9de-0000-4000-8000-000000000010",
  "nome": "Maria Exemplo",
  "telefone_e164": "+5511955550101",
  "email": "maria@exemplo.test",
  "documento": null,
  "bloqueado": false,
  "criado_em": "2026-10-12T14:30:00.000Z",
  "atributos": { "plano": "ouro", "cliente_desde": "2024" },
  "created": true
}

Campos do corpo

Se o contato já existe, os atributos enviados são juntados aos atuais e os campos name, email e document que você enviou preenchem o contato. O telefone é guardado na forma canônica, com o nono dígito.

Para falhar em vez de mesclar, use POST /v1/contacts?upsert=false. Um identificador já usado responde 409 com contact_phone_in_use, contact_identity_in_use ou contact_email_in_use.

Buscar contatos

curl -s "https://http.pipebr.app/v1/contacts?telefone=%2B5511955550101" \
  -H "Authorization: Bearer $PIPE_CHAVE"

Editar um contato

PATCH /v1/contacts/:id muda só o que você enviar. Um campo enviado com null é apagado. Os atributos são sempre juntados aos existentes, nunca substituídos.

curl -s -X PATCH https://http.pipebr.app/v1/contacts/b3a1c9de-0000-4000-8000-000000000010 \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"email": "maria.nova@exemplo.test", "atributos": {"plano": "diamante"}}'

Um telefone que já pertence a outro contato dá 409 contact_phone_in_use. A edição não muda as identidades de canal nem o campo bloqueado.

Histórico do contato

GET /v1/contacts/:id/messages junta, em ordem, as mensagens dos tickets do contato e as da conversa com o bot, mesmo quando nunca houve ticket.

Cada mensagem traz source (bot ou ticket), conversationId e executionId. Notas internas nunca aparecem.

Etiquetas do contato

Para aplicar, envie o id da etiqueta:

curl -s -X POST https://http.pipebr.app/v1/contacts/b3a1c9de-0000-4000-8000-000000000010/labels \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"etiqueta_id": "b3a1c9de-0000-4000-8000-000000000500"}'

A resposta traz etiqueta_id, nome e aplicada. Para descobrir os ids, use GET /v1/labels?scope=contato, em Consultar cadastros.