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	A field 'paidforapi' with value false A field 'apitoken' with the invalid token
`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',
  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