Custom sidebar apps

Custom sidebar apps let you display dynamic, rich content related to a ticket right in your project's sidebar.

Setup a custom sidebar app

Start by navigating to Settings → Project → Sidebar apps. Then add a new app and add your API url, name as well as optional security headers for your API.

Continue reading with the API guide below.

Setup the sidebar app API

When a ticket is viewed, our system automatically sends a POST request to your app's API URL. This request includes the following parameters:

• ticketId: The unique identifier of the ticket.

• session: Information about the current user session.

• sessions: Data for one or more related sessions.

Your API endpoint should be configured to handle POST requests and allow cross-origin requests (wildcard CORS).

Expected JSON Response

Your API must return a valid JSON response with the following structure:

{
  "content": [
    {
      "type": "text",
      "text": "Hello, world!"
    },
    {
      "type": "image",
      "image": "https://via.placeholder.com/150"
    },
    {
      "type": "button",
      "button": {
        "label": "Click me",
        "url": "https://www.google.com"
      }
    },
    {
      "type": "html",
      "html": "<h1>Hello, world!</h1>"
    },
    {
      "type": "key-value",
      "keyValue": [
        {
          "key": "Name",
          "value": "John"
        },
        {
          "key": "Age",
          "value": "25"
        },
        {
          "key": "City",
          "value": "New York"
        }
      ]
    }
  ]
}

Response Element Types

• text: Displays plain text.
  Example: { "type": "text", "text": "Hello, world!" }

• image: Displays an image from the provided URL.
  Example: { "type": "image", "image": "https://via.placeholder.com/150" }

• button: Renders a clickable button. The button object must include a label and a url.
  Example: { "type": "button", "button": { "label": "Click me", "url": "https://www.google.com" } }

• html: Renders raw HTML content.
  Example: { "type": "html", "html": "<h1>Hello, world!</h1>" }

• key-value: Displays a list of key-value pairs.
  Example:

  {
    "type": "key-value",
    "keyValue": [
      { "key": "Name", "value": "John" },
      { "key": "Age", "value": "25" },
      { "key": "City", "value": "New York" }
    ]
  }

Guidelines for Implementation

1. Handling the POST Request:
   Ensure your API endpoint accepts POST requests with the parameters ticketId, session, and sessions. Process these parameters to generate a tailored response.

2. CORS Configuration:
   Your API must include the appropriate headers to allow wildcard cross-origin requests, ensuring that our system can fetch your content without restrictions.

3. Valid JSON Response:
   Return a well-structured JSON object as shown above. Each content type should include all required properties.

4. Customizing Content:
   You can mix different content types to create a rich sidebar experience. Adapt the response based on the context of the ticket or session data provided.

By following these guidelines, you can build a custom sidebar app that enhances ticket details with interactive and informative content. Happy coding!