Skip to main content
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)

// 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" } }
      }
    }
  ]
}

// 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:

​
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
    • 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:

​
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: 
    {
  "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: 
    {
  "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": "<p>This is a sample comment</p>",
        "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.

​
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 for a complete list of available events. 
// 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: 
// 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"
    }
  }
}