Gestionar contactos

​

Qué es

​

Antes de comenzar

• Normaliza los números de teléfono al formato E.164.
• Decide qué sistema es el propietario de cada campo del perfil.
• Define los atributos personalizados antes de escribir valores que dependan de ellos.
• Establece reglas de consentimiento y retención para los datos de los clientes.

​

Cómo funciona

1. Crea un contacto con un número de teléfono único.
2. Guarda el ID de contacto devuelto.
3. Recupera o lista contactos mediante identificadores y filtros.
4. Actualiza el perfil, etiquetas, atributos personalizados o la asignación de propietario.
5. Elimina el contacto cuando tu política de retención lo requiera.

​

Solicitud

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"
  }'

​

Respuesta

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

​

Búsqueda y paginación

​

Consistencia de datos

• Selecciona un sistema de registro único para cada campo.
• Trata las actualizaciones de Webhook como eventos, no como registros de reemplazo completos garantizados.
• Haz que las importaciones y los consumidores de Webhook sean idempotentes.
• Evita sobrescribir datos de clientes más recientes con eventos retrasados.

​

Límites y resolución de problemas

• Los números de teléfono deben usar el formato E.164.
• Las direcciones de correo electrónico, cuando se proporcionan, deben ser únicas y válidas.
• Un contacto admite hasta 50 etiquetas, con límites de longitud específicos por campo.
• Usa el endpoint de atributos de contacto para consultar los atributos personalizados disponibles.
• Oculta datos personales en registros generales y evidencias de soporte.