Gerenciar contatos

​

O que é

​

Antes de começar

• Normalize os números de telefone para o formato E.164.
• Defina qual sistema é o proprietário de cada campo do perfil.
• Defina os atributos personalizados antes de gravar valores que dependem deles.
• Estabeleça regras de consentimento e retenção para os dados dos clientes.

​

Como funciona

1. Crie um contato com um número de telefone exclusivo.
2. Armazene o ID de contato retornado.
3. Recupere ou liste contatos por identificadores e filtros.
4. Atualize o perfil, tags, atributos personalizados ou propriedade.
5. Exclua o contato quando sua política de retenção exigir.

​

Requisição

curl --request POST https://api.ycloud.com/v2/contact/contacts \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "nickname": "Avery",
    "phoneNumber": "+16315551111",
    "countryCode": "US",
    "email": "avery@example.com",
    "tags": ["customer", "vip"],
    "customAttributes": [
      {
        "name": "plan",
        "value": "premium"
      }
    ],
    "ownerEmail": "sales@example.com"
  }'

​

Resposta

{
  "id": "1693364594105000000",
  "nickname": "Avery",
  "phoneNumber": "+16315551111",
  "countryCode": "US",
  "email": "avery@example.com",
  "tags": ["customer", "vip"],
  "sourceType": "API",
  "createTime": "2026-07-16T12:00:00.000Z"
}

​

Busca e paginação

​

Consistência de dados

• Selecione um sistema de registro oficial (system of record) para cada campo.
• Trate as atualizações de webhook como eventos, e não como registros de substituição completa garantidos.
• Torne as importações e os consumidores de webhook idempotentes.
• Evite sobrescrever dados mais recentes do cliente com eventos atrasados.

​

Limites e solução de problemas

• Os números de telefone devem usar o formato E.164.
• Os endereços de e-mail, quando fornecidos, devem ser exclusivos e válidos.
• Um contato suporta até 50 tags, com limites de comprimento específicos por campo.
• Use o endpoint de atributos de contato para descobrir os atributos personalizados disponíveis.
• Oculte dados pessoais de logs gerais e evidências de suporte.