canonical: https://jentic.com/apis/organization.gladly.com/gladly

# Organization Gladly Gladly API

Jentic publishes the only available OpenAPI specification for Gladly API, keeping it validated and agent-ready. Gladly is a customer service platform that treats each customer as a single lifelong conversation rather than a stream of tickets, unifying voice, chat, SMS, email, and custom channels in one timeline. The API spans 67 endpoints across conversations, conversation items, customer profiles, tasks, message automation sessions, agents, inboxes, topics, exports, and webhooks. It also includes a Lookup API contract that lets external services feed customer context back into the agent workspace.

## For AI agents

Send messages, manage conversations and tasks, sync customer profiles, and configure webhooks across the Gladly customer service platform.

## Scope

Does not handle payment processing, order fulfillment, or marketing campaign send - use for customer conversations, profiles, and support workflows only.

## Capabilities

- Send an SMS to a customer through POST `/api/v1/communications/sms`
- Post or fetch conversation items including replies and notes via `/api/v1/conversation-items` endpoints
- Create or update customer profiles using POST and PATCH on `/api/v1/customer-profiles`
- Open, update, and comment on tasks tied to a customer through `/api/v1/tasks` and `/api/v1/customers/{customerId}/tasks`
- Drive automated chat sessions with POST `/api/v1/message-automation/sessions/{sessionId}/messages` and handoff endpoints
- Register webhooks for real-time conversation events via POST `/api/v1/webhooks`
- Schedule and retrieve export jobs of conversation data through `/api/v1/export/jobs`

## Use cases

### Bot to Human Handoff

Customer service teams running automated chat want a clean handoff when the bot can't resolve an issue. Gladly's message automation endpoints let the bot post messages, close the session, or hand off to a live agent through POST `/api/v1/message-automation/sessions/{sessionId}/handoff` so the conversation continues in the human inbox without losing context.

Example prompt: POST to `/api/v1/message-automation/sessions/{sessionId}/handoff` with the target inbox id when bot confidence drops below threshold.

### Unified Customer Profile Sync

Order, loyalty, and subscription systems each hold a different slice of the customer. Pushing those into Gladly via POST `/api/v1/customer-profiles` or PATCH `/api/v1/customer-profiles/{customerId}` gives agents a single timeline view at the moment of contact, reducing average handle time on returns and billing calls.

Example prompt: PATCH `/api/v1/customer-profiles/{customerId}` with updated lifetime spend and last order id when the e-commerce backend fires a profile-changed event.

### Outbound SMS Campaigns from Conversations

Agents triggering proactive outreach (delivery delay, appointment reminder, refund confirmed) can use POST `/api/v1/communications/sms` to send targeted SMS that lands in the customer's existing Gladly timeline, keeping outbound and inbound history together for the next agent.

Example prompt: POST `/api/v1/communications/sms` with the customer's phone number and a templated 'your refund is on its way' body.

### Conversation Data Export for Analytics

Operations teams pull conversation history into a warehouse to compute CSAT trends or train models. POST `/api/v1/reports` plus `/api/v1/export/jobs` lets a scheduled job request an export, poll status, and download the resulting files for downstream ETL.

Example prompt: POST `/api/v1/reports` for a date range, then poll GET `/api/v1/export/jobs/{jobId}` until ready and download via `/files/{filename}.`

### Agent-Driven Customer Service via Jentic

AI agents that triage tickets, draft replies, or schedule follow-ups can drive Gladly through Jentic without learning all 67 endpoints. Jentic exposes operations by intent and isolates the basic auth credentials in the vault.

Example prompt: Use Jentic to search 'reply to a customer conversation', load the schema for POST `/api/v1/conversation-items/{itemId}/reply`, and execute with the drafted response.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/communications/sms` | Send SMS to a customer |
| GET | `/api/v1/conversations/{conversationId}` | Retrieve a conversation |
| POST | `/api/v1/conversation-items/{itemId}/reply` | Reply to a conversation item |
| POST | `/api/v1/customer-profiles` | Create a customer profile |
| PATCH | `/api/v1/customer-profiles/{customerId}` | Update a customer profile |
| POST | `/api/v1/tasks` | Create a task |
| POST | `/api/v1/message-automation/sessions/{sessionId}/handoff` | Hand off bot session to human agent |
| POST | `/api/v1/webhooks` | Register a webhook subscription |

## Key resources

- **Communications** — Send SMS and post messages to custom channels
- **Conversations** — Read and update conversations and their items
- **Customer Profiles** — Create, read, and update unified customer records
- **Tasks** — Open and track work items tied to conversations or customers
- **Message Automation** — Drive bot sessions and handoffs
- **Webhooks** — Register subscribers for conversation and task events
- **Exports** — Schedule and retrieve bulk data exports
- **Agents and Inboxes** — Read agent and inbox state for routing

## Why Jentic

- **Setup:** Wiring the Gladly API by hand means setting up its basic auth against your organization.gladly.com host and mapping the conversation, customer-profile, and task routes yourself. Through Jentic you install once, import Gladly from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** You choose which Gladly operations the agent may call, so you can limit it to the operations it needs, such as reading a conversation or creating a customer profile, while sending an SMS or handing off a message-automation session stays out of the allowed set unless you add them.
- **Credential handling:** Your Gladly basic-auth credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'reply to a conversation item' or 'create a customer profile', and Jentic returns the matching Gladly operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Zendesk API** — Zendesk is a ticket-centric support platform - a common alternative to Gladly's conversation-centric model.
- **Kustomer API** — Kustomer also unifies customer history across channels into a timeline, similar to Gladly.
- **Intercom API** — Intercom focuses on in-app chat and messenger conversations that often feed Gladly as a secondary channel.

## FAQ

### Why is there no official OpenAPI spec for Gladly API?

Gladly publishes a developer portal but not a maintained OpenAPI document. Jentic generates and maintains this spec so that AI agents and developers can call Gladly API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Gladly API use?

Gladly uses HTTP Basic authentication with an agent-bound API token created from the API Tokens settings page. Through Jentic the token is stored encrypted in the vault and only injected at execution time.

### Can I send an SMS to a customer through the Gladly API?

Yes. POST `/api/v1/communications/sms` accepts a customer id and message body and posts the SMS into the customer's Gladly timeline so it appears alongside other channels.

### What are the rate limits for the Gladly API?

The OpenAPI spec does not declare numeric rate limits. Gladly enforces per-organization throttling that varies by plan - consult developer.gladly.com or Gladly support before bulk profile syncs.

### How do I hand off a bot session to a human agent through Jentic?

Search Jentic for 'hand off chat to a human', load the schema for POST `/api/v1/message-automation/sessions/{sessionId}/handoff`, and execute with the session id and target inbox id.

### Does the Gladly API support webhooks for new conversation events?

Yes. POST `/api/v1/webhooks` registers a subscription, and GET `/api/v1/webhooks` lists existing subscriptions. PATCH and DELETE on `/api/v1/webhooks/{webhookId}` update or remove a subscription.

### Can I limit what my agent is allowed to do with the Gladly API?

Yes. Because you run Jentic One yourself, your own rules decide which Gladly operations and credentials the agent can use. You can allow it to read a conversation or create a customer profile while keeping higher-impact calls such as sending an SMS through POST `/api/v1/communications/sms` or handing off a message-automation session out of the allowed set unless you explicitly add them. The basic-auth credential is injected only at execution time for the operations you permit.