> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thena.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> Learn how the Thena apps framework works and how to build with it
The Thena Apps framework provides a foundation for building applications that extend and enhance Thena. This guide explains the core concepts and architecture to help you start building.
## Developer quickstart
1. Create an app manifest with minimal fields (name, scopes, events).
2. Host a webhook that accepts platform events and returns 2xx quickly.
3. Use the bot token from the installation event to call Activities/APIs.
4. Store configuration securely and reference it from Activities.
5. Add one Activity and one event handler end-to-end before scaling up.
### Minimal app (manifest + handler)
```json theme={null}
// manifest.json
{
"app": { "name": "Sample App" },
"scopes": { "required": ["tickets:read", "comments:write"] },
"events": { "subscribe": [{ "event": "ticket:created" }] },
"activities": [
{
"name": "notify_assignee",
"description": "Notify the assigned agent",
"http_config": {
"headers": { "Content-Type": "application/json" },
"httpVerb": "POST",
"endpoint_url": "https://example.com/notify"
},
"request_schema": {
"type": "object",
"properties": { "ticketId": { "type": "string" } }
}
}
]
}
```
```javascript theme={null}
// webhook.js
import express from "express";
const app = express();
app.use(express.json());
app.post("/webhook/app", async (req, res) => {
const event = req.body;
if (!event?.eventType) return res.status(400).send("Invalid");
res.status(200).send("OK");
if (event.eventType === "ticket:created") {
await notifyAssignee(event.payload.ticket);
}
});
app.listen(3001);
```
### Production checklist
* Enforce idempotency using `eventId`.
* Process asynchronously; keep webhook fast.
* Store bot tokens and configuration securely.
* Validate event payloads and activity responses.
* Add monitoring for failed events/activities.
## Architecture overview
At its core, the Apps framework uses an event-driven architecture that enables real-time communication between your app and Thena. Here's how the main components work together:
```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '20px', 'fontFamily': 'Inter', 'primaryColor': '#6A00FF', 'primaryTextColor': '#fff' }}}%%
flowchart LR
A[Your App]:::highlight --> B[Event System]
B --> C[Authentication]
B --> D[Authorization]
B --> E[Events]
B --> F[Activities]
classDef default fill:#f4f4f4,stroke:#333,stroke-width:2px,color:#333;
classDef highlight fill:#6A00FF,stroke:#333,stroke-width:2px,color:#fff;
linkStyle default stroke:#6A00FF,stroke-width:2px;
```
### Core components
1. Event system
* Central communication layer
* Handles real-time updates
* Manages app lifecycle events
* Processes user interactions
2. Authentication
* Bot token-based authentication
* Secure installation flow
* Automatic token management
3. Authorization
* Permission-based access control
* Scoped resource access
* User-level permissions
4. Events
* Subscribe to [platform events](/platform/platform-events)
* Publish custom events
* Handle real-time updates
* Process state changes
5. Activities
* HTTP-based operations
* Pre-configured API calls
* Custom business logic
* External service integration
## How events work
The event system is the primary way your app communicates with Thena. Here's a typical event flow:
```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '20px', 'fontFamily': 'Inter', 'primaryColor': '#6A00FF', 'primaryTextColor': '#fff', 'noteBkgColor': '#f4f4f4', 'noteTextColor': '#333' }}}%%
sequenceDiagram
participant App as Your App
participant Events as Event System
participant Thena as Thena Platform
Note over App,Thena: Installation Flow
Thena->>Events: 1. App installation event
Events->>App: 2. Send bot token
Note over App,Thena: Event Subscription
App->>Events: 3. Subscribe to events
Note over App,Thena: Real-time Communication
Thena->>Events: 4. Platform event occurs
Events->>App: 5. Event notification
App->>Events: 6. Process & respond
Events->>Thena: 7. Update platform state
```
### Key events
1. Installation events
When your app is installed in a workspace, you'll receive an installation event with the bot token and other details:
```typescript theme={null}
{
"event_type": "app:installation",
"application_id": "APP123456789",
"application_name": "Sample App",
"application_metadata": {
"title": "Sample Integration",
"category": "productivity",
"capabilities": [
"Data Management",
"Workflow Automation"
],
"pricing": {
"monthly": 999,
"yearly": 9990
},
"rating": 4.5
},
"bot_id": "BOT123456",
"bot_token": "pk_live_sample.token123456",
"organization_id": "ORG123456",
"team_ids": ["TEAM123456"],
"created_at": "2024-01-01T12:00:00.000Z",
"created_by": "USER123456"
}
```
2. Platform events
Your app can subscribe to various platform events. Here's an example of a ticket comment event:
```typescript theme={null}
{
"message": {
"actor": {
"id": "USER123456",
"email": "user@example.com",
"type": "ORG_ADMIN"
},
"eventType": "ticket:comment:added",
"orgId": "ORG123456",
"payload": {
"comment": {
"id": "COMMENT123456",
"content": "This is a sample comment",
"contentHtml": "This is a sample comment
",
"contentMarkdown": "This is a sample comment",
"commentType": "comment",
"commentVisibility": "public",
"author": {
"id": "USER123456",
"name": "Sample User",
"email": "user@example.com",
"avatarUrl": "https://example.com/avatar.jpg"
},
"teamId": "TEAM123456",
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
},
"ticket": {
"id": "TICKET123456",
"title": "Sample support request"
}
},
"eventId": "EVENT123456",
"timestamp": "1704110400000"
},
"xWebhookEvent": true
}
```
For a complete list of available events and their payloads, see our [platform events documentation](/platform/platform-events).
## Security model
The Apps framework uses a token-based security model:
1. Installation security
* Secure bot token generation
* Workspace-scoped access
2. Request authentication
* Token validation on each request
* Request signing
* Secure payload transmission
3. Data access control
* Resource-level permissions
* User context validation
* Data encryption in transit
## Building blocks
### Events
Events let you respond to changes in Thena. See our [platform events documentation](/platform/platform-events) for a complete list of available events.
```typescript theme={null}
// Example event subscription
{
events: {
// Installation event handler
'app:installation': async (event) => {
const { bot_token, organization_id, team_ids } = event;
// Store bot token securely
// Initialize app for the organization
},
// Ticket comment event handler
'ticket:comment:added': async (event) => {
const {
payload: {
comment: { content, author },
ticket: { id: ticketId }
}
} = event.message;
// Process new comment
// Update external systems
}
}
}
```
### Activities
Activities are pre-configured HTTP operations:
```json theme={null}
// Example activity definition
{
"name": "create_contact",
"description": "Creates a new contact in Hubspot",
"http_config": {
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ${configuration.required_settings.hubspot_api_key}"
},
"httpVerb": "POST",
"endpoint_url": "https://api.hubapi.com/crm/v3/objects/contacts"
},
"request_schema": {
"properties": {
"email": {
"type": "string",
"description": "Contact's email address"
},
"company": {
"type": "string",
"description": "Company name"
},
"lastname": {
"type": "string",
"description": "Contact's last name"
},
"firstname": {
"type": "string",
"description": "Contact's first name"
}
}
},
"response_schema": {
"id": {
"type": "string"
},
"metadata": {
"type": "object",
"description": "Additional information about the created contact"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"properties": {
"type": "object"
}
}
}
```