API Reference

Introduction

The Events API lets you build a timeline of all your customers' interactions from any source. An event can be any event that your application or system can associate with a user, conversation, bugs, etc. Examples include Error Encountered, Checkout Completed, etc.

Structure

Events have the following structure:

  • objectType: the Atlas object you're associating an event with. This determines where the event will show up, how it will show up in search results, and how it can be used in conditional logic. Examples are conversations, customers, accounts, and session recordings.
  • objectId: the Atlas id of the object you're associating the event with.
  • externalId: the database id of the object in your own SOR (system of records, eg -- HRMS, CRM, or application database)
  • name: an expressive name for the the event -- eg: "User Visited the Help center Article"
  • description: Plain text or HTML formatted string that can provide your agents the most important highlights at a quick glance -- eg: Stripe payment event saying "$49.99 paid via credit card."
  • icon: A URL or a unicode character that can be rendered in the agent timeline so that your agents can recognize the type of event effortlessly
2000

Custom event in Customer Timeline, associated with a Customer

1024

Custom event in Customer Timeline, associated with a Ticket

In case the Events are not visible on the timeline, please check the event logs - Event Logs - and make sure that the - processingStatus is LINKED.

Object Associations

The full list of Atlas entities (for objectType):

  • CONVERSATION
  • ACCOUNT
  • CUSTOMER
  • USER (AGENT)
  • CHATBOT
  • COMPANY
  • HELPCENTER
  • SESSION RECORDING

Sample Request Payload

{
    // Mandatory; fields that are used for determining what and where to show events in Atlas
    "objectType": "CUSTOMER",
    "objectId": "c19a7d78-37a1-4ee4-9e68-aae0d4c93f7e",
    "name": "Atlas Helpcenter",                    
    "description": "Viewed HelpCenter Article - How does it work?",
    "icon": "📖",

    "externalId": "195959",     

    "payload": {
        "company": "Atlas",
        "hq": "Dellas",
        "give": "superpower",
        "to": "your agents",
        "filter": "all the agents",
    }
}

Note: Only the Primary Atlas Object gets validated, and would return an error 404 if the Primary Object is not found. Related Objects are linked via a background job, and it's done in the best effort manner. If the related objects are not found, the error gets suppressed.

Responses

HTTP API Responses:

  • Successful responses to submitted events return 200 Accepted with an Event Linked response
  • Unauthorized access will be rejected with a 401 Unauthorized or 403 Forbidden response code.
  • Server errors will return a 500 response code and may contain an error message in the body.
  • Error responses based on whether we have found the linked objects
    • 404 Object Not found