Rastrear eventos personalizados

​

Qué es

​

Antes de comenzar

• Elija un nombre de evento estable que no cambie con los textos de la interfaz.
• Identifique el contacto asociado con cada evento.
• Defina las propiedades del evento y sus tipos de datos.
• Decida qué marca de tiempo del sistema representa cuándo ocurrió la actividad.

​

Cómo funciona

1. Cree una definición de evento.
2. Agregue o actualice definiciones de propiedades a medida que el esquema evolucione.
3. Envíe ocurrencias de eventos utilizando el nombre exacto de la definición.
4. Asocie cada ocurrencia con un ID de contacto, número de teléfono o nombre de usuario de Meta.
5. Monitoree eventos rechazados y discrepancias en el esquema.

​

Solicitud

​

Crear una definición de evento

curl --request POST https://api.ycloud.com/v2/event/definitions \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "order_completed",
    "label": "Order completed",
    "description": "A customer completed an order.",
    "objectType": "CONTACT",
    "properties": [
      {
        "name": "order_value",
        "label": "Order value",
        "type": "NUMBER"
      }
    ]
  }'

​

Elegir un identificador de contacto

​

Enviar un evento por número de teléfono

curl --request POST https://api.ycloud.com/v2/event/events \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "eventName": "order_completed",
    "occurTime": "2026-07-16T12:00:00.000Z",
    "contactPhoneNumber": "+16315551111",
    "properties": {
      "order_value": 99.9
    }
  }'

​

Enviar un evento por nombre de usuario

curl --request POST https://api.ycloud.com/v2/event/events \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "eventName": "order_completed",
    "occurTime": "2026-07-16T12:00:00.000Z",
    "contactUsername": "customer_demo",
    "properties": {
      "order_value": 99.9
    }
  }'

​

Respuesta

{
  "name": "order_completed",
  "label": "Order completed",
  "objectType": "CONTACT",
  "properties": [
    {
      "name": "order_value",
      "label": "Order value",
      "type": "NUMBER"
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{}

​

Evolución del esquema

• Agregue nuevas propiedades opcionales siempre que sea posible.
• No reutilice el nombre de una propiedad existente para un significado diferente.
• Valide los tipos antes de enviar eventos.
• Mantenga estables los nombres de eventos y de propiedades entre entornos.
• Cree una nueva versión del nombre del evento cuando un cambio semántico incompatible sea inevitable.

​

Límites y solución de problemas

• La definición del evento debe existir antes de que se envíe una ocurrencia.
• Los nombres y valores de las propiedades deben coincidir con la definición.
• Utilice RFC 3339 para occurTime.
• Asegúrese de que el identificador de contacto se resuelva en el cliente deseado en su cuenta.
• Para contactUsername, verifique que el contacto ya exista y que el nombre de usuario coincida con el valor guardado sin un @ inicial.
• Omita los identificadores que no desee que YCloud utilice. Un número de teléfono proporcionado tiene prioridad sobre un nombre de usuario.
• Una respuesta 200 confirma la aceptación, no que una automatización posterior haya finalizado.