API

If you don't want to use our predefined support contact form, you can also make your own frontend interface to your customers. You can then communicate with our backend to create a ticket to your workspace using our REST API.

In order to create a ticket call the following API route as POST request:

http://localhost/api/{workspace}/ticket/create

Where {workspace} is your workspace hash name. You can find it in your system API settings. Also you need an API token for every request to our API for security reasons. An API token is automatically generated on registration, but you can generate new tokens in the system settings menu. The following post data fields are supported:

Field Description Required
apitoken The workspace API token Required
subject The subject of the ticket Required, minimum 5 chars
text The ticket text Required, maximum 4096 chars
name The name of the customer Required
email The e-mail address of the customer Required
type Ticket type Required, must match the ID of one of your created ticket types
prio Ticket priority Required, 1 = low, 2 = medium, 3 = high
attachment A file to be attached Optional

The API endpoint will return a JSON response in order to provide your frontend with the operation result. The JSON response will contain a status code of the operation named 'code' and a field 'data' that holds additional data depending on the result of the operation. Also it will hold the concerned workspace. The following response status codes are possible:

Code Description Additional data
404 Not Found
  • The workspace could not be found
  • The specified ticket type could not be found
  • No workspace found: none
  • Ticket type not found: field ‚ticket_type‘ with the request value
403 Forbidden
  • The API access has not yet been purchased
  • The request API token is invalid
  • The request was suspected to be spam
  • A field 'paidforapi' with value false
  • A field 'apitoken' with the invalid token
  • A field 'spam' that is set to true
500 Internal Server Error
  • The post data is invalid
  • The ticket could not be created
  • Invalid post data: field ‚invalid_fields‘ as an array containing an array for each failed post data item with the fields ‚name‘ for the field name and ‚value‘ for the failed value
  • Ticket not created: A field ‚data‘ with the data that could not be stored
429 Too Many Requests You tried to create too many tickets in a period of time Field ‚ticket_wait_time‘ that holds the time in seconds you have to wait until you may create a ticket again
201 Created The ticket has been created Field ‚data‘ containing the stored ticket data

An example response can look like the following:
{
  "code": "201",
  "workspace": "(A workspace hash name)",
  "data": {
    (Ticket creation data)
  }
}


Further API requests


Get ticket information

In order to query specific ticket information you can call:
http://localhost/api/{workspace}/ticket/info

Arguments:

Field Description Required
apitoken The workspace API token Required
hash The hash of a ticket of your workspace Required

Response:
{
  "code": "200",
  "workspace": "(A workspace hash name)",
  "data": {
    (Ticket information data)
  }
}


Get ticket thread

To retrieve ticket thread posts you can call:
http://localhost/api/{workspace}/ticket/thread

Arguments:

Field Description Required
apitoken The workspace API token Required
hash The hash of a ticket of your workspace Required
paginate Thread posts below this ID will be returned Optional
limit Maximum amount of returned thread posts Optional, default 10

Response:
{
  "code": "200",
  "workspace": "(A workspace hash name)",
  "ticket": "(The associated ticket hash)",
  "data": {
    (Ticket thread data)
  }
}


Get ticket attachments

In order to get a list of attachments you can call:
http://localhost/api/{workspace}/ticket/attachments

Arguments:

Field Description Required
apitoken The workspace API token Required
hash The hash of a ticket of your workspace Required

Response:
{
  "code": "200",
  "workspace": "(A workspace hash name)",
  "ticket": "(The associated ticket hash)",
  "data": {
    (Ticket attachment data)
  }
}


Add customer comment

In order to add a customer comment you can call:
http://localhost/api/{workspace}/ticket/comment/add/customer

Arguments:

Field Description Required
apitoken The workspace API token Required
hash The hash of a ticket of your workspace Required
text The text content Required

Response:
{
  "code": "200",
  "workspace": "(A workspace hash name)",
  "ticket": "(The associated ticket hash)",
  "cmt_id": "(ID of the added comment)"
}


Edit customer comment

In order to edit a customer comment you can call:
http://localhost/api/{workspace}/ticket/comment/edit/customer

Arguments:

Field Description Required
apitoken The workspace API token Required
hash The hash of a ticket of your workspace Required
cmt_id The ID of the comment Required
text The new text content to be stored Required

Response:
{
  "code": "200",
  "workspace": "(A workspace hash name)",
  "ticket": "(The associated ticket hash)",
  "cmt_id": "(ID of the edited comment)"
}


Add ticket attachment

In order to add a ticket attachment you can call:
http://localhost/api/{workspace}/ticket/attachment/add

Arguments:

Field Description Required
apitoken The workspace API token Required
hash The hash of a ticket of your workspace Required
attachment File to be added Required

Response:
{
  "code": "200",
  "workspace": "(A workspace hash name)",
  "ticket": "(The associated ticket hash)",
  "file": {
    (Attachment info)
  }
}


Delete ticket attachment

In order to delete a ticket attachment you can call:
http://localhost/api/{workspace}/ticket/attachment/delete

Arguments:

Field Description Required
apitoken The workspace API token Required
hash The hash of a ticket of your workspace Required
file_id The ID of the attachment Required

Response:
{
  "code": "200",
  "workspace": "(A workspace hash name)",
  "ticket": "(The associated ticket hash)",
  "success": "(true on success)"
}


Widget

You can also use the embeddable widget in order to let users create support requests comfortably from your website. When enabled and activated then a support icon will be shown in the bottom right corner of your page which users can use to open a form to enter their support request data. After successfully submitting the form, a new ticket will be created for the requesting user.

In order to embed the widget, you need to activate the feature in your system settings. There is a separate key for the widget feature in order to keep things distinguishable. Similar to the REST API key, you can also always generate a new widget API key whenever you want.

The following code describes a basic widget initialization.

<script src="https://www.helprealm.io/js/widget.js"></script>

<div id="support-widget"></div>

let widget = new HelpRealmWidget({
  elem: '#support-widget',
  workspace: 'your-workspace-hash',
  apiKey: 'your-widget-api-key',
  header: 'url/to/your/header/image.png',
  logo: 'url/to/your/logo/image.png',
  button: 'url/to/your/button/image.png',
  btnborder: 'widget button border style on opened form',
  fileUpload: true,
  lang: {
    title: 'Contact Us!',
    lblInputName: 'Enter your name',
    lblInputEmail: 'Enter your E-Mail',
    lblInputSubject: 'What is your topic?',
    lblInputMessage: 'What is on your mind?',
    lblInputFile: 'Attachment (optional)',
    btnSubmit: 'Submit',
    error: 'Elem {elem} is invalid or missing',
    access: 'Access denied!',
},
  ticket: {
    type: 1,
    prio: 1
  },
});


The following methods are also available:

Method Description
showWidget(flag)   Show or hide widget depending on the boolean flag value
toggleWidget() Toggle the widget depending on the current visibility state
isOpened() Returns true or false depending on whether the widget support form is currently openend
release() Should be called whenever your widget instance shall be released