Casey

Casey is a fully opensource headless support case management service. Every interaction with Casey is done either via HTTP or e-mail. To open a case, ask the user for useful information before sending a HTTP request to create the case. This will send e-mails to the poster, as well as a configurable number of team members, and from this point on the entire communication can be performed in an official but slightly anonymized fashion.

Users will only exchange messages with one single address; your support address. This is true no matter how many participants a case has. That means there is no risk of internal e-mail addresses leaking (unless explicitly quoted in the messages exchanged).

Features

• API tokens for access control.
• Create cases via HTTP API for customers or visitors to your website.
• Interact with the case via email or HTTP API for maximum flexibility.
• Call custom webhooks on case events.
• Provide privacy by proxying all messages to a support email account.

Caveats/Known Issues

• The IMAP inbox adapter has not been tested.

Installation

With docker:

$ docker run --name casey -i -t \
    -v$PWD/data:/application/var \      # Mount directory for data
    -p12002:12002 \                     # Port 12002
    dev.noccylabs.info/casey/casey

With docker-compose:

services:
  casey:
    image: dev.noccylabs.info/casey/casey:latest
    ports: 
      - 127.0.01:12002:12002
    volumes:
      - ./casey-data:/application/var

Natively (requires PHP 8.3+):

$ git clone https://dev.noccylabs.info/casey/casey
$ cd casey
$ composer install
$ bin/caseyd

Initial user token

An initial admin user is created if the database is empty on startup. An associated access token will be created, and printed to standard output. So, after the first start, remember to run docker compose logs casey or similar, if the daemon isn't running against stdout.

Interacting

Directly

Step 1: Create your team

POST /api/casey/v1/persons
Content-Type: application/json
X-Token: <youradmintoken>

{
    "name": "Ben Foo",
    "email": "ben@domain.tld",
    "team": true
}

Step 2: Create your tokens

Find your admin user UUID by GETting /api/casey/v1/persons.

POST /api/casey/v1/person/<adminuuid>/tokens
Content-Type: application/json
X-Token: <youradmintoken>

{
    "roles": [ "PERSONS", "CASES" ]
}

Use the resulting token in your frontend application. This token will only be able to manage persons and cases.

Step 3: Create a case

POST /api/casey/v1/cases
Content-Type: application/json

{
    "creator": {
        "name": "Some User",
        "email": "some.user@other.tld"
    },
    "subject": "I found a bug",
    "message": "There is a bug over there!"
}

You can include additional data for indexing and analysis: category is a string categorizing the case (ex. support, questions, warranty), tags is an array of tags to attach to the case, and if that's not enough, you can use available keys in the meta object as long as they will not collide with any internal meta keys. It is recommended that you prefix your keys, f.ex. instead of orderNumber use myPlatformOrderNumber.

Post a message to the case

While this is normally done by sending an e-mail message including the case reference, you can also post messages via the HTTP API.

The case UUID for {uuid} can be found in the create case response.

POST /api/casey/v1/case/{uuid}/messages
Content-Type: application/json

{ 
    "from": "ben@domain.tld",
    "message": "Hello Some User,\n\nWe are excited to hear about the bug. Can you tell us more?"
}

Retrieve the case

GET /api/casey/v1/case/{uuid}

This will retrieve the full case, suitable for presentation on a webpage.

Note: This response may contain e-mail addresses and other private information of the participants, and should never be passed directly to the user's browser.

Configuration

See doc/Configuration.md for the available configuration keys.

Setting a config file

With docker-compose:

  environment:
    CASEY_CONFIG_FILE=/path/to/config.yaml

Running native:

$ caseyd --config /path/to/config.yaml

Runtime configuration

Get configuration:

GET /api/casey/v1/config

Update one or more keys:

POST /api/casey/v1/config
Content-Type: application/json

[
    { "mailSyncTimer": 120 }
]

Commit the keys to primary config file:

POST /api/casey/v1/config/commit

Note

You need to start Casey with a config file in order to commit config. The config file may be empty, but it must be writable.

Web Interface

There is a basic web interface included, primarily for development purposes. This interface is entirely unprotected, which is yet another reason to not make Casey publically accessible on the internet.