Rastrear eventos personalizados

​

O que é

​

Antes de começar

• Escolha um nome estável para o evento que não mude com o texto de exibição.
• Identifique o contato associado a cada evento.
• Defina as propriedades do evento e seus tipos de dados.
• Decida qual timestamp do sistema representa quando a atividade ocorreu.

​

Como funciona

1. Crie uma definição de evento.
2. Adicione ou atualize definições de propriedades conforme o esquema evolui.
3. Envie ocorrências de eventos usando exatamente o nome da definição.
4. Associe cada ocorrência a um ID de contato, número de telefone ou nome de usuário da Meta.
5. Monitore eventos rejeitados e incompatibilidades de esquema.

​

Requisição

​

Criar uma definição 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"
      }
    ]
  }'

​

Escolher um identificador de contato

​

Enviar um evento por número de telefone

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 um evento por nome de usuário

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

​

Resposta

{
  "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

{}

​

Evolução do esquema

• Adicione novas propriedades opcionais sempre que possível.
• Não reutilize o nome de uma propriedade existente para um significado diferente.
• Valide os tipos antes de enviar eventos.
• Mantenha os nomes de eventos e de propriedades estáveis entre ambientes.
• Crie versões para o nome do evento quando uma alteração semântica significativa for inevitável.

​

Limites e solução de problemas

• A definição do evento deve existir antes que uma ocorrência seja enviada.
• Os nomes e valores das propriedades devem corresponder à definição.
• Use RFC 3339 para occurTime.
• Certifique-se de que o identificador de contato corresponda ao cliente desejado em sua conta.
• Para contactUsername, verifique se o contato já existe e se o nome de usuário corresponde ao valor salvo sem o @ inicial.
• Omita identificadores que você não deseja que a YCloud use. Um número de telefone fornecido tem precedência sobre um nome de usuário.
• Uma resposta 200 confirma o aceite, não que uma automação posterior foi concluída.