AtlasGo to Atlas↗️

No results

Help CenterCustom DataCustom Events

Custom Events

Last updated April 11, 2023

Custom events provide a generic structure that allows you to send key events in your customers’ journey to Atlas so that it can be visualized in the customer timeline, used as a trigger for workflows (eg, in Chatbots), and used as a search filter criteria.

This article will explain the structure of custom events and give a brief primer on how you add them. For instrumentation best practices for custom events for your product, take a look at  this article . For technical details on how to implement custom events, see  these docs .


Custom events have the following basic structure:

# Atlas event
    // Atlas object type to be associated with the event
    "objectType": "CUSTOMER", 
    // Atlas object ID
    "objectId": "c19a7d78-37a1-4ee4-9e68-aae0d4c93f7e",

    // ID of the Atlas Objects within any system of record - eg - CRM, Application Database
    "externalId": "12123", 
    // expressive action name that can capture the esssence of the tracked activity
    "name": "Employee Paid", 
    // description of event hown in the main body of the event
    // could be formatted using HTML
    "description": "<p>🎉 Congratulations, today is your payday! <i>$5,393.17</i> was deposited into your bank account.<p>",

    // optional: details about the tracked activity
    "payload": { 
          "shifts_completed": 22,
          "overtime_accumulated": 0,
          "tax_at_source": 12,
    // optional: URL or unicode character that can be rendered in the agent timeline so that your agents can recognize the type of event effortlessly
    "icon": "url",

The above event would show up in the customer timeline like the following:

Custom Events

Custom events can also be shown in the timeline and info pane of session recordings.

Custom Events


There are two ways to add an event to Atlas:

  1. API: create a custom event  that can be sent through a web request
  2. Segment: connect to Atlas as a destination

(If you are new to instrumenting your app with events, take a look at our  best practices .)

All event types will be shown in the  App Config > Data > Custom Events  page where you can specify where they are shown and get a quick read on their structure.

Custom Events

If you’ve got any questions about how to best setup events for your company, feel free to reach out to us via chat or email at

Was this article helpful?