Gladly Events API

openapi: 3.0.1
info:
  title: Gladly Agents Events API
  version: '1.0'
  description: '# Introducing the Gladly API


    At Gladly, we believe that customer service is best when it''s a conversation.

    That means more than just helping customers with one-off questions or issues: it''s about making them feel known, valued, and respected for the individuals they are.


    The Gladly API was built to help facilitate those relationships, providing agents with the rich customer context

    they need to deliver seamless experiences that make customers feel like they''re more than just a number in a sea of others.


    # Overview


    You can integrate easily with Gladly by calling Gladly''s [REST API](#section/Overview/REST-API)

    and implementing the [Lookup API](#section/Overview/Lookup-API) to provide data from your own services.


    Some examples of what you do through Gladly APIs include managing customer profile data, interacting with a customer''s timeline,

    providing the latest information about a customer''s orders, and more.


    ## REST API


    Clients can access the **REST API** via HTTPS at your organization''s Gladly domain (e.g. `https://{organization}.gladly.com`).


    Resources follow REST semantics and utilize industry-standard HTTP verbs, response codes, and authentication schemes.

    In addition, all responses and payloads are in JSON with consistent error codes and formats.


    ## Lookup API


    The Gladly **Lookup API** allows your organization to provide data services to power the agent''s experience with a complete view of your customers''

    information, transactions, and activity. You can provide a web service that implements the Lookup API and Gladly will call it when that data is needed.


    Like the REST API, the Lookup API is specified using REST semantics, and exchanges JSON requests and responses authenticated and signed with secure keys.


    Gladly will perform lookups when certain activities occur within Gladly, such as when a customer''s profile is loaded.


    A detailed overview of Lookup Adaptor architecture, requests, resposnes and more can be found [here](https://help.gladly.com/developer/docs/lookup-adapter-introduction).


    ## Testing


    Test the myriad possibilities of the Gladly API in a safe, secure space. We''ll enable the Gladly API in a separate sandbox environment, so you can experiment freely without impacting your production environment (or vice versa).


    Your sandbox environment is accessible at `https://{organization}.gladly.qa`, where `organization` is your company name. For specific API endpoints, see documentation below.


    # Getting Started


    Think of this section as getting the keys to unlocking your access to the Gladly APIs.

    First, you''ll need to set up an account with the necessary API [permissions](#/section/Getting-Started/Permissions).

    With these permissions, you can then go on to create the [API Token(s)](#section/Getting-Started/Creating-API-Tokens) you need to access Gladly''s API [resources](#section/Overview/Resources).


    ## Permissions


    Gladly Administrators can set API permissions on an agent-by-agent basis.

    We''ll discuss how this maps to API access in the section on [authentication](#section/Authentication) below.


    To allow a user to create API tokens and access the API:

    1. Log in to your Gladly instance.

    2. Open the menu on the top left-hand corner of the page.

    3. Navigate to **Settings** > **Users*

    4. Search and click the user profile you wish to give access to.

    5. You''ll see a permission called **API User**. Select it, while making sure to keep the user''s **Agent** role intact.

    6. Hit **Save** to give access.


    ![Agent profile screen](assets/permissions-agent.png)


    We recommend creating a dedicated user to make API calls, whose account won''t be used for agent and organization management.

    This will help you with any future audits of API activity vs. agent activity.


    ## Creating API Tokens


    You must create an API token to access Gladly API resources (see above [Permissions](#/section/Getting-Started/Permissions)).

    If your profile already has access to the **API User** permission, you''ll see a menu item titled **More settings**. Click **More settings**:


    ![API Token Menu](assets/permissions-token-nav.png)


    Click **API Tokens**, then the **Create Token** button on the upper right-hand corner of the page:


    ![API Token Add](assets/permissions-token-add.png)


    A token will be generated and named, by default, **New Token** (though depending on whether you have existing tokens, it may be named New Token 2, or New Token 3, etc.).

    You can rename the token to something more easily referenceable by clicking the name to edit.


    This token will be associated with your agent profile, which we refer to as the API User in this document.


    ![API Token View](assets/permissions-token-view.png)


    For security purposes, you''ll only see a new token once before you navigate away from the page.


    ## Replacing/Rotating API Tokens


    Should you lose this token, or wish to rotate your application keys, you can do the following:


    1. Generate a new token.

    2. Store the new token in a secure location.

    3. Delete the old token.

    4. Update your applications/scripts with the new token.


    # Authentication


    <!-- ReDoc-Inject: <security-definitions> -->'
servers:
- url: https://{organization}.gladly.com/api/v1
  description: Production
  variables:
    organization:
      default: organization
      description: Your Gladly organization subdomain
- url: https://{organization}.gladly.qa/api/v1
  description: Sandbox
  variables:
    organization:
      default: organization
      description: Your Gladly QA organization subdomain
security:
- basicAuth: []
tags:
- name: Events
  description: 'An **Event** is something that has happened in Gladly. The Events API allows you to extract event details from the past 24 hours.

    '
paths:
  /api/v1/events:
    parameters:
    - name: startAt
      required: true
      in: query
      description: 'Starting time of the events interval. This is based on the `timestamp` field which indicates when the event was recorded. Must be from last 24 hours.


        The date should be in ISO 8601 format.

        '
      schema:
        type: string
        example: '2020-04-13T19:27:34-09:00'
    - name: endAt
      in: query
      description: 'Ending time of the events interval. This is based on the `timestamp` field which indicates when the event was recorded. If unspecified, current time will be implied.


        The date should be in ISO 8601 format.

        '
      required: false
      schema:
        type: string
        example: '2020-04-13T20:27:12-09:00'
    - name: entities
      required: true
      in: query
      description: 'Entity types that have associated events. Any number of types is acceptable and at least one must be present


        Available Types: `AGENT_AVAILABILITY`, `AGENT_STATUS`, `CONTACT`, `CONVERSATION`, `CUSTOMER`, `CUSTOMER_PROFILE`, `PAYMENT_REQUEST`,`TASK`

        '
      schema:
        type: array
        example:
        - AGENT_AVAILABILITY
        - AGENT_STATUS
    get:
      tags:
      - Events
      summary: List Events
      description: "Returns a stream of events for the specified entities within the given time range. Responses are streamed using JSONL.\n\nEvents are up to 15 seconds behind real-time. \n\n```\n/api/v1/events?startAt=2020-05-20T14:00:00Z&entities=AGENT_STATUS&entities=AGENT_AVAILABILITY\n```\n"
      responses:
        '200':
          description: Events Streaming Response
          content:
            application/x-jsonlines:
              schema:
                title: Event Response Schemas
                oneOf:
                - title: Agent Availability Focus Entered
                  type: object
                  required:
                  - id
                  - type
                  - timestamp
                  - initiator
                  - content
                  properties:
                    id:
                      type: string
                      description: Unique event ID
                      example: zGaHXjD4SR-moMR9LbULDa
                    type:
                      type: string
                      example: AGENT_AVAILABILITY/FOCUS_ENTERED
                      enum:
                      - AGENT_AVAILABILITY/FOCUS_ENTERED
                    timestamp:
                      type: string
                      format: ISO 8601
                      description: Time the event was recorded
                      example: '2019-07-03T04:30:12.07Z'
                    initiator:
                      $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
                    content:
                      title: Content
                      description: Content for event
                      required:
                      - agentId
                      - context
                      properties:
                        agentId:
                          type: string
                          description: ID of the agent who entered or exited focus.
                          example: zGaHXjD4SR-moMR9LbULDa
                        context:
                          description: The state of the agent immediately before the event occurred.
                          required:
                          - availableFor
                          properties:
                            availableFor:
                              type: array
                              enum:
                              - MAIL
                              - MESSAGING
                              - TASK
                              - VOICE
                              description: 'The set of channel types for which the agent is available for.

                                '
                              example:
                              - MAIL
                              - TASK
                              - VOICE
                - title: Agent Availability Focus Exited
                  type: object
                  required:
                  - id
                  - type
                  - timestamp
                  - initiator
                  - content
                  properties:
                    id:
                      type: string
                      description: Unique event ID
                      example: zGaHXjD4SR-moMR9LbULDa
                    type:
                      type: string
                      example: AGENT_AVAILABILITY/FOCUS_EXITED
                      enum:
                      - AGENT_AVAILABILITY/FOCUS_EXITED
                    timestamp:
                      type: string
                      format: ISO 8601
                      description: Time the event was recorded
                      example: '2019-07-03T04:30:12.07Z'
                    initiator:
                      $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
                    content:
                      $ref: '#/paths/~1api~1v1~1events/get/responses/200/content/application~1x-jsonlines/schema/oneOf/0/properties/content'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/1'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/2'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/3'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/4'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/5'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/7'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/8'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/9'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/10'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/11'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/12'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/13'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/14'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/15'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/16'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/17'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/18'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/19'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/20'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/21'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/22'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/23'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/24'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/26'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/27'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/28'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/29'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/30'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/32'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/36'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/37'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/38'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/39'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/40'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/41'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/42'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/43'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/44'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/45'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/46'
                - $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/47'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                invalid parameter:
                  value:
                    errors:
                    - attr: startAt
                      code: invalid
                      detail: endAt must occur after startAt
components:
  schemas:
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          example:
          - attr: content
            code: blank
            detail: content cannot be blank
    Error:
      type: object
      properties:
        attr:
          type: string
          description: Identifies the field causing the error
        code:
          type: string
          description: Code indicating the error type
        detail:
          type: string
          description: More details describing what went wrong
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: 'Gladly API uses token-based **Basic Authentication**. API tokens are associated with designated Gladly users.

        To create and use an API token, your user must have the API User permission. An API token can be used to perform any API request without restriction.


        | user name   | password  |

        | ----------- | --------- |

        | agent email | API token |


        The credentials must be passed via an `Authorization` HTTP header. All requests must be made over HTTPS.


        ```shell

        curl -u user@organization.com:$GLADLY_API_TOKEN \

        https://organization.gladly.com/api/v1/organization

        ```

        '
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth — username is the API user email; password is the API token. Requires the "API User" permission.
x-tagGroups:
- name: REST API
  tags:
  - Agents
  - Public Answer
  - Answer Management
  - Audiences
  - Business Hours
  - Communications
  - Conversations
  - Customers
  - Events
  - Export
  - Freeform Topics
  - Inboxes
  - Organization
  - Proactive Conversations
  - Reports
  - Tasks
  - Teams
  - User Identity
  - Topics
  - Webhooks
- name: Webhooks
  tags:
  - Summary
  - Payloads
- name: Lookup API
  tags:
  - Customer Lookup
- name: Resources
  tags:
  - Versioning
  - Error Handling
  - Rate Limit
  - Rich Content
  - Launching Soon