Getting Started with Gladly App Platform

Getting Started with Gladly App Platform

What is the Gladly App Platform?

The Gladly App Platform empowers you to seamlessly connect external systems to Gladly, enabling you to bring in data, trigger actions, and extend the Gladly experience for your heroes and customers. With the App Platform, you can integrate third-party APIs, internal databases, or any external service, and make that data available in Gladly’s powerful, unified interface.

What can I build?

Expose Data and Actions to Sidekick:

Seamlessly make external data and actions available to Gladly’s Sidekick, enabling automations, workflows, and hero assistance powered by real-time information from your connected systems.

Data Integrations:

Pull customer, order, or ticket data from external systems and make it available in Gladly, so heroes and automations have a complete view of the customer journey.

Actions:

Trigger operations in external systems (like creating a return, updating a record, or sending a notification) directly from Gladly or Sidekick.

Custom UI Extensions:

Enhance the Gladly hero interface with custom cards and templates that display external data or provide new workflows.

You don’t need to write any code for Gladly App Platform Apps—simply provide configuration for the data you want Gladly to access, the actions you want it to take in external systems, and any custom UI elements you want to present to your heroes.

Who is this document for?

This document is intended for those new to the Gladly App Platform, or those who want to get a refresher on basic concepts. This guide is an introduction, but it will prepare you to dive into more advanced concepts in the Gladly developer tutorials.

How do I get started?

If you are able to fetch data from your systems using cURL or Postman, then you are good to go with App Platform! You should have a basic understanding of what data is available in your systems, and the APIs and URLs needed to get that data. For example, how would you look up a customer, and how would you use that response to get their orders from the last 30 days?

Prerequisites

appcfg

The Gladly App Platform uses a command-line tool called appcfg to scaffold, test, and manage your app.

• Download the latest appcfg release for your operating system and architecture
• Follow the installation instructions for your operating system (macOS, Linux, Windows).
• Verify installation by running appcfg --version
  • if you see the version number, then it is installed properly

Development environment

Use your preferred editor to edit configuration and template files.

Let’s go!

For this getting started guide, we’ll be using Gladly’s sample order management system. The concepts we’ll cover will be applicable to your systems, but the configuration details and data available may differ.

1. Scaffold a New App

Download the configuration

To get started, you can clone the repository at https://github.com/gladly/gladly-getting-started; it contains the directory tree and all of the configuration files we’ll cover in this guide.

Create the sample app yourself

If you want to create all of the directories and files yourself, we salute you, and we will provide directory paths for all files in the guide. Use the Gladly App Platform CLI (appcfg) to create a new app project; the command below will generate the root directory and the manifest.json file, which contains app metadata and configuration.

appcfg init --app-name gladly-getting-started --author mydomain.com. --description my-description
cd gladly-getting-started

Either way, the directory tree should look similar to this when we are finished:

.
|-- manifest.json
|-- authentication
|   \-- headers
|       \-- apiToken.gtpl
\-- data
    |-- data_schema.graphql
    \-- pull
        |-- customers
        |   |-- config.json
        |   |-- customer.json
        |   |-- external_id.gtpl
        |   |-- request_url.gtpl
        |   |-- response_transformation.gtpl
        |   \-- _run
        |       \-- data
        |           \-- customer.json
        |-- orders
        |   |-- config.json
        |   |-- external_id.gtpl
        |   |-- external_parent_id.gtpl
        |   |-- request_url.gtpl
        |   \-- response_transformation.gtpl
        |-- _run
        |   \-- data
        |       \-- customer.json
        |-- data
        |   \-- pull
        |       \-- _run_
        |           \-- data
        \-- _run_
            \-- data

You’re now ready to start defining your data types and connecting to the Gladly OMS!

2. Explore the Gladly OMS API

Let’s familiarize ourselves with the data in the Gladly OMS. Use curl to fetch a customer from the Gladly OMS by email address:

URL:
https://gladly-sample-oms.vercel.app/api/[email protected]

Headers:

Content-Type: application/json

apiToken: fake-token

request:

% curl "https://gladly-sample-oms.vercel.app/api/[email protected]" --header 'Content-Type: application/json' --header 'apiToken:fake-token'

response:

{"id":"TW9ydG9uX1NoaWVsZHNAZ21haWwuY29t","fullName":"Hardy Paucek","phones":["+54842998988"],"emails":["[email protected]","[email protected]","[email protected]"],"ltv":"$119.65}

Now let’s look up orders for this customer using their [email protected] email address:

request:

% curl "https://gladly-sample-oms.vercel.app/api/[email protected]" --header 'Content-Type: application/json' --header 'apiToken: fake-token'

response:

[
  {
    "id": "c2fecdc9-18c7-46ef-a781-9e39f21e3d22",
    "orderNumber": "LoPHjxVa",
    "status": "shipping",
    "shippingAddress": "3450 Lang Club Apt. 246",
    "billingAddress": "",
    "orderDate": "2022-02-25T15:43:05.781Z",
    "customerId": "TW9ydG9uX1NoaWVsZHNAZ21haWwuY29t",
    "lineItems": [
      {
        "id": "76450393-d33a-4853-8d6e-1043528e0b09",
        "quantity": 4,
        "price": "42.00",
        "productId": "6ac3c3c8-0fa1-4d01-ac5b-5ac2eb545ace",
        "status": "shipping"
      },
      {
        "id": "6cd27ff1-113e-4c13-a04d-214cbfe98425",
        "quantity": 3,
        "price": "699.00",
        "productId": "4b346620-870a-4fa0-a7e9-6f240ce8c91f",
        "status": "delivered"
      },
      {
        "id": "5ae6759b-76f2-4b0e-ab2b-a8f334adb858",
        "quantity": 3,
        "price": "306.00",
        "productId": "e09761fd-0f55-47a6-8c83-e00014d76462",
        "status": "shipping"
      },
      {
        "id": "27f8da8d-8431-48b3-85a6-41586165c3b8",
        "quantity": 3,
        "price": "921.00",
        "productId": "18db998a-14fb-41aa-927c-238e3348e02f",
        "status": "delivered"
      }
    ],
    "shippingSpeed": "expedited",
    "totalPrice": "1968",
    "shippingAndHandling": "684.00"
  }
]

3. Design your data types

Now that we’ve familiarized ourselves with the available data, we can start defining the data that we want to use.

data/data_schema.graphql

What:

This file defines your app’s GraphQL data schema. It describes the types (such as Customer, Order, LineItem, etc.), their fields, and the relationships between them. It also specifies which types are associated with data pulls using the @dataType directive, and how parent-child or child-child relationships are resolved using directives like @parentId and @childIds.

Why:

The data_schema.graphql file is the foundation of your Gladly App Platform app’s data model. It tells Gladly:

• What data structures to expect and expose in the API.
• How to map external system data into Gladly’s GraphQL types.
• How to resolve relationships (e.g., which orders belong to which customer).
• Which types can be pulled or synced from external systems.

A well-defined schema ensures that your data pulls, actions, and UI integrations are consistent, reliable, and easy to maintain. It also enables Gladly to automatically handle complex data relationships and present a unified view to agents and customers.

Edit data/data_schema.graphql to add the definition for the Customer type:

Customer Type

type Customer @dataType(name: "customer", version: "1.0") {
    id: ID!
    emails: [String]
    fullName: String
    ltv: Currency
    numberOfOrders: Int
    phones: [String]
    state: String
    orders: [Order] @parentId(template: "{{.id}}")
}

This schema matches the structure of the customer JSON returned by the Gladly OMS, allowing Gladly to understand and query customer data returned.

About the Parent-Child Relationship: orders Field

The orders field in the Customer type is annotated with the @parentId(template: "{{.id}}") directive. This establishes a parent-child relationship between customers and orders in the Gladly data model.

• For each customer, Gladly will automatically retrieve all Order objects where the customerId field matches the customer's id.
• When you pull customer data, the platform will also pull and attach all related orders to the orders field of each customer.
• This enables you to query a customer and get their full order history in a single operation, reflecting the real-world relationship where a customer can have multiple orders.

Edit data/data_schema.graphql to add the definition for the Order types:

Order Type

type Order @dataType(name: "order", version: "1.0") {
  id: ID!
  orderNumber: String
  status: String
  shippingAddress: String
  billingAddress: String
  orderDate: String
  customerId: String
  lineItems: [LineItem]
  shippingSpeed: String
  totalPrice: String
  shippingAndHandling: String
  lineItems: [LineItem]
}

This schema matches the structure of the order JSON returned by the Gladly OMS, allowing Gladly to understand and query order data returned.

Edit data/data_schema.graphql to add the definitions for the LineItem, and Product types:

LineItem Type

type LineItem {
  id: ID!
  quantity: Int
  price: String
  product: Product @childIds(template: "{{.productId}}")
  status: String
}

About @childIds on the Product field

The @childIds(template: "{{.productId}}") directive on the product field in the LineItem type tells Gladly how to resolve the relationship between a line item and its associated product.

• For each LineItem, Gladly will use the value of the productId field to look up and fetch the corresponding Product object.
• The product field on the LineItem will be automatically populated with the full product details, based on the referenced ID.
• This enables you to see not just the product ID, but all relevant product information directly within each line item.

Product Type

type Product @dataType(name: "sample_oms_product", version: "1.1") {
  id: ID
  imageUrl: String
  name: String
  productType: String
  sku: String
}

Queries

Define the queries that we’d like to run (customers and orders, which we defined previously):

type Query {
  customers: [Customer]
  orders: [Order]
}

About the Query Type

The Query type is the main access point for reading data in your API. It exposes the top-level queries that clients can use to retrieve lists of customers and orders.

• The customers field allows you to query for a list of Customer objects.
• The orders field allows you to query for a list of Order objects.
• These fields are the root-level queries that clients (like Gladly or your frontend) can use to fetch customer and order data.

When done, the data/data_schema.graphql file should look similar to this (comments were added in as an example):

type Customer @dataType(name: "customer", version: "1.0") {
    id: ID!
    emails: [String]
    fullName: String
    ltv: Currency
    numberOfOrders: Int
    phones: [String]
    state: String
    orders: [Order] @parentId(template: "{{.id}}")
}

type Order @dataType(name: "order", version: "1.0") {
  id: ID
  orderNumber: String
  status: String
  shippingAddress: String
  billingAddress: String
  orderDate: String
  customerId: String
  shippingSpeed: String
  totalPrice: Currency
  shippingAndHandling: Currency
  lineItems: [LineItem]
}

type LineItem {
  id: String
  quantity: Int
  price: Currency
  product: Product @childIds(template: "{{.productId}}")
  status: String
}

type Product @dataType(name: "product", version: "1.1") {
  id: ID
  imageUrl: String
  name: String
  productType: String
  sku: String
}

type Query {
  customers: [Customer]
  orders: [Order]
}

4. Create data pulls for customers and orders

What is a Data Pull?

A data pull is a configuration in your Gladly App Platform app that defines how to fetch data from an external system (like the Gladly OMS) and make it available to Gladly via GraphQL. In other words, it is how you connect Gladly to external data sources, letting Gladly fetch and use that data in a standardized, queryable way.

When Gladly (or Sidekick) needs order data, it triggers your data pull, which:

• Builds the request to the external API (using templates)
• Fetches the data
• Transforms the response into the shape defined in your GraphQL schema
• Returns the data to Gladly, where it can be queried and used in automations

Why use templates?

App Platform Apps use Go text templates to generate HTTP requests and transform the responses declaratively — they describe what you want, not how to build it step-by-step. They are also human-readable, and show what the eventual output would look like. For App Platform Apps, template files have a .gtpl extensions.

Data Pull Files

These files define the configurations for your data pull.

/authentication/headers/apiToken.gtpl

What:

This is a Go template file that generates the authentication header that the Gladly OMS requires. The apiKey will be substituted here when running a data pull via our command-line tool, appcfg.

Why:

The Gladly OMS needs to authenticate the user. Note that the Gladly OMS does not require a particular apiKey — you can use a key of your choosing.

Bearer {{ .integration.secrets.apiKey }}

Files for customer data pulls

/data/pull/customers/config.json

What:

This file defines the configuration for your data pull. It specifies:

• The data type and version (must match your GraphQL schema)
• The HTTP method to use (GET, POST, etc.)
• (Optionally) Content type, dependencies, and other settings

Why:

Gladly uses this file to understand:

• What kind of data you are pulling (e.g., "order" objects)
• How to make the request (e.g., should it be a GET or POST?)
• How to link this data pull to the correct GraphQL type for querying

Example:

{
  "dataType": { "name": "customer", "version": "1.0" },
  "httpMethod": "GET"
}

**/data/pull/customers/**request_url.gtpl

What:

This is a Go template file that generates the URL for the external API request.

It can use variables from the context (like the customer’s email) to build dynamic URLs.

Why:

APIs often require parameters (like customer email or ID) in the URL.

By templating the URL, you ensure each request fetches the right data for the current context (e.g., the right customer).

Example:

This template uses the first customer email address for lookup. At runtime, {{ index.customer.emails 0 }} is replaced with the actual email address.

https://gladly-sample-oms.vercel.app/api/customers?emailAddress={{ index .customer.emails 0 }}

/data/pull/customers/response_transformation.gtpl

What:

This Go template transforms the raw API response into the shape defined by your GraphQL schema.

It maps fields from the external API’s JSON to the fields expected by Gladly.

Why:

External APIs rarely return data in exactly the format Gladly expects.

This template lets you reshape, rename, or reformat the data so it matches your Order type (or whatever type you’re pulling).

Example:

{
"id": "{{ .rawData.id }}",
"fullName": "{{ .rawData.fullName }}",
"phones": {{ toJson .rawData.phones }},
"emails": {{ toJson .rawData.emails }},
"ltv": "{{ .rawData.ltv }}"
}

• This loops over each order in the API response and outputs an array of objects matching your GraphQL schema.

/data/pull/customers/external_id.gtpl

What:

This is a Go template file that extracts the unique identifier (ID) from each object returned by your data pull.

It is evaluated for every object in the array output by your response_transformation.gtpl.

Why:

Gladly needs to know the unique ID for each object (e.g., each order, customer, etc.) so it can:

• Track and deduplicate records
• Link related data (e.g., orders to customers)
• Efficiently update or reference specific objects

By providing a template for the ID, you ensure Gladly can always extract the correct unique identifier, even if the field name or structure is different from the default.

Example:

{{- .id -}}

• This template simply outputs the id field from each object.
• If your unique ID field had a different name (e.g., orderId), you would use {{- .orderId -}}.
• The dashes on either side of .id strip whitespace.

Files for order data pulls

/data/pull/orders/config.json

What:

Defines the data type and HTTP method for the orders data pull.

Why:

This file tells Gladly which GraphQL type this data pull is associated with (in this case, order), and how to make the HTTP request (e.g., GET). It is required for every data pull configuration.

{
    "dataType": { "name": "order", "version": "1.0" },
    "httpMethod": "GET"
}

/data/pull/orders/request_url.gtpl

What:

A Go text template that generates the URL for the REST API call to fetch orders.

Why:

This template constructs the endpoint Gladly will call to retrieve order data. It can use fields from the parent object (like .customer.id) to fetch orders for a specific customer, enabling parent-child relationships.

https://gladly-sample-oms.vercel.app/api/orders?customerId={{ .customer.id }}

/data/pull/orders/response_transformation.gtpl

What:

A Go text template that transforms the raw API response into the expected GraphQL Order type.

Why:

The external system’s response may not match your schema exactly. This template maps and formats the response data so it fits your GraphQL type, ensuring Gladly can use it as expected.

[
  {{- range $i, $order := .rawData }}
    {{- if $i}},{{ end }}
    {
      "id": "{{ $order.id }}",
      "orderNumber": "{{ $order.orderNumber }}",
      "status": "{{ $order.status }}",
      "shippingAddress": "{{ $order.shippingAddress }}",
      "billingAddress": "{{ $order.billingAddress }}",
      "orderDate": "{{ $order.orderDate }}",
      "customerId": "{{ $order.customerId }}",
      "lineItems": {{ toJson $order.lineItems }},
      "shippingSpeed": "{{ $order.shippingSpeed }}",
      "totalPrice": "{{ $order.totalPrice }}",
      "shippingAndHandling": "{{ $order.shippingAndHandling }}"
    }
  {{- end }}
]

/data/pull/orders/external_id.gtpl

What:

A Go text template that extracts the unique ID from each order object.

Why:

Gladly uses this template to determine the unique identifier for each order. This is important for deduplication, updates, and establishing relationships with other data types.

{{- .id -}}

/data/pull/orders/external_parent_id.gtpl

What:

A Go text template that extracts the parent customer’s ID from each order object.

Why:

This template enables the parent-child relationship between customers and orders. It tells Gladly how to associate each order with its parent customer, so orders can be automatically linked to the correct customer in your data model.

{{- .id -}}

5. Test Your Data Pulls

gladly-getting-started/data/pull/customers/customer.json

This file is used to pass customer info to the data pull. In this case we’re passing in an array of email addresses, and the customer id. This is done to emulate the context that Gladly will pass to your app when running in production. The request_url.gtpl that we configured above will lookup the customer using their first email address, [email protected]. You won’t need to create this file with your production app — Gladly will automatically pass customer context to your app so that it can look up the intended customer.

gladly-getting-started/data/pull/customers/customer.json

{
    "emails": ["[email protected]","[email protected]"],
    "id":"TW9ydG9uX1NoaWVsZHNAZ21haWwuY29t"
}

You can inject the contents of customer.json into the command line like so:

appcfg run data-pull -c "$(cat data/pull/customers/customer.json)" -r . -s '{"apiToken":"fake-token"}'

If you prefer to include the customer data by hand, you can add it inline right after the --customer flag.

appcfg run data-pull --customer '{"emails": ["[email protected]","[email protected]"],"id":"TW9ydG9uX1NoaWVsZHNAZ21haWwuY29t"}' -r . -s '{"apiToken":"fake-token"}'

The results are the same for both command lines. Note below that appcfg has taken the emailAddress=**{{ index .customer.emails 0 }}** from gladly-getting-started/data/pull/customers/request_url.gtpl, and substituted the first email in the emails array, [email protected].

Using root: .

=============
Run data pull
=============

------------
HTTP request
------------

URL
---
https://gladly-sample-oms.vercel.app/api/[email protected]

headers
-------
Accept: application/json, text/xml, application/xml
Apitoken: fake-token

body
----

-------------
HTTP response
-------------

status
------
200 OK

headers
-------
Age: 0
Cache-Control: public, max-age=0, must-revalidate
Content-Type: application/json
Date: Wed, 16 Jul 2025 17:16:32 GMT
Server: Vercel
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
X-Matched-Path: /api/customers
X-Vercel-Cache: MISS
X-Vercel-Id: cle1::iad1::q6nxb-1752686192183-8342ec270bff

body
----
{"id":"TW9ydG9uX1NoaWVsZHNAZ21haWwuY29t","fullName":"Hardy Paucek","phones":["+54842998988"],"emails":["[email protected]","[email protected]","[email protected]"],"ltv":"$119.65"}

------------
HTTP request
------------

URL
---
https://gladly-sample-oms.vercel.app/api/orders?customerId=TW9ydG9uX1NoaWVsZHNAZ21haWwuY29t

headers
-------
Accept: application/json, text/xml, application/xml
Apitoken: fake-token

body
----

-------------
HTTP response
-------------

status
------
200 OK

headers
-------
Age: 0
Cache-Control: public, max-age=0, must-revalidate
Content-Type: application/json
Date: Wed, 16 Jul 2025 17:16:32 GMT
Server: Vercel
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
X-Matched-Path: /api/orders
X-Vercel-Cache: MISS
X-Vercel-Id: cle1::iad1::7xbn6-1752686192183-4e19067b9c2b

body
----
[{"id":"c2fecdc9-18c7-46ef-a781-9e39f21e3d22","orderNumber":"LoPHjxVa","status":"shipping","shippingAddress":"3450 Lang Club Apt. 246","billingAddress":"","orderDate":"2022-02-27T11:10:51.576Z","customerId":"TW9ydG9uX1NoaWVsZHNAZ21haWwuY29t","lineItems":[{"id":"76450393-d33a-4853-8d6e-1043528e0b09","quantity":4,"price":"42.00","productId":"6ac3c3c8-0fa1-4d01-ac5b-5ac2eb545ace","status":"shipping"},{"id":"6cd27ff1-113e-4c13-a04d-214cbfe98425","quantity":3,"price":"699.00","productId":"4b346620-870a-4fa0-a7e9-6f240ce8c91f","status":"delivered"},{"id":"5ae6759b-76f2-4b0e-ab2b-a8f334adb858","quantity":3,"price":"306.00","productId":"e09761fd-0f55-47a6-8c83-e00014d76462","status":"shipping"},{"id":"27f8da8d-8431-48b3-85a6-41586165c3b8","quantity":3,"price":"921.00","productId":"18db998a-14fb-41aa-927c-238e3348e02f","status":"delivered"}],"shippingSpeed":"expedited","totalPrice":"1968","shippingAndHandling":"684.00"}]

mydomain.com/gladly-getting-started/v1/data/types/customer-1.0
--------------------------------------------------------------
[
  {
    "emails": [
      "[email protected]",
      "[email protected]",
      "[email protected]"
    ],
    "fullName": "Hardy Paucek",
    "id": "TW9ydG9uX1NoaWVsZHNAZ21haWwuY29t",
    "ltv": "$119.65",
    "phones": [
      "+54842998988"
    ]
  }
]

mydomain.com/gladly-getting-started/v1/data/types/order-1.0
-----------------------------------------------------------
[
  {
    "billingAddress": "",
    "customerId": "TW9ydG9uX1NoaWVsZHNAZ21haWwuY29t",
    "id": "c2fecdc9-18c7-46ef-a781-9e39f21e3d22",
    "lineItems": [
      {
        "id": "76450393-d33a-4853-8d6e-1043528e0b09",
        "price": "42.00",
        "productId": "6ac3c3c8-0fa1-4d01-ac5b-5ac2eb545ace",
        "quantity": 4,
        "status": "shipping"
      },
      {
        "id": "6cd27ff1-113e-4c13-a04d-214cbfe98425",
        "price": "699.00",
        "productId": "4b346620-870a-4fa0-a7e9-6f240ce8c91f",
        "quantity": 3,
        "status": "delivered"
      },
      {
        "id": "5ae6759b-76f2-4b0e-ab2b-a8f334adb858",
        "price": "306.00",
        "productId": "e09761fd-0f55-47a6-8c83-e00014d76462",
        "quantity": 3,
        "status": "shipping"
      },
      {
        "id": "27f8da8d-8431-48b3-85a6-41586165c3b8",
        "price": "921.00",
        "productId": "18db998a-14fb-41aa-927c-238e3348e02f",
        "quantity": 3,
        "status": "delivered"
      }
    ],
    "orderDate": "2022-02-27T11:10:51.576Z",
    "orderNumber": "LoPHjxVa",
    "shippingAddress": "3450 Lang Club Apt. 246",
    "shippingAndHandling": "684.00",
    "shippingSpeed": "expedited",
    "status": "shipping",
    "totalPrice": "1968"
  }
]

Congratulations on running your first successful data pull with appcfg! 🎉.

You now have a working foundation for integrating your order management system with Gladly. Once you configure your own app for your own systems, you can enable a wide range of powerful use cases in your Gladly production environment:

• App Cards:

  Display rich, real-time data from your external system directly in the Gladly Agent UI. For example, show customer order history, loyalty status, or product recommendations as app cards during conversations.

• Actions (Mutations):

  Allow agents to take action from within Gladly—such as creating, updating, or canceling orders, issuing refunds, or updating customer profiles—by configuring actions in your app.

• Automated Workflows:

  Trigger data pulls or actions automatically based on customer events, conversation context, or business rules, streamlining agent workflows and improving customer experience.

• Custom Data Views:

  Surface custom data (like product details, shipment tracking, or account balances) in context, so agents have all the information they need at their fingertips.

• Secure, Real-Time Integrations:

  Use production credentials, OAuth, and secure headers to connect to live systems, ensuring data is always up-to-date and protected.

6. Next Steps

Now that you have a solid foundation, visit https://help.gladly.com/developer-tutorials/docs to learn more about what you can build with Gladly App Platform.

7. Troubleshooting and Resources

If you encounter issues:

• Refer to the directory tree and files at https://github.com/gladly/gladly-getting-started, and compare against your current state to figure out where the problem might be.
• Check the Gladly App Platform documentation for context and template help.
• Use curl to verify OMS API responses and authentication.
• Check https://help.gladly.com/developer-tutorials/docs for tutorials and documentation.