How to connect a custom support endpoint

Overview

This article explains how to connect a custom support endpoint to Ferndesk. This feature allows you to integrate your own ticketing or support system, even if it's not natively supported by Ferndesk.

Prerequisites

• You must have a publicly accessible URL that returns a JSON response.

• You must have permissions to manage integrations in Ferndesk.

Steps

1. Navigate to the Integrations page in your Ferndesk settings.

2. Click the "Add Integration" button. This will take you to the Connect an integration page.

3. Select "Support Endpoint" from the list of available integrations.

4. In the configuration dialog, you will see a field labeled "Source URL".

5. Enter the URL of your custom support endpoint. The placeholder text for this field is https://company.com/support-endpoint.json?startDate=2025-01-01.

6. Click the "Save" button to connect the endpoint.

Verify the setup

Once you've connected your custom support endpoint, you can verify that it's working correctly by creating an audit. If the connection is successful, you should see conversations from your custom support system included in the audit.

JSON Format

The custom support endpoint must return a JSON response with a specific format. The root object should contain a conversations key, which holds an array of conversation objects. Each conversation object must have an id, lastMessageAt timestamp, and an array of messages. Each message object within the array should include an id, role (either user or c), content, and a createdAt timestamp.

Here's an example of the expected JSON format:

{
  "conversations": [
    {
      "id": "conv_12345",
      "url": "https://support.mycompany.com/conversations/12345",
      "lastMessageAt": "2023-10-27T14:30:00Z",
      "messages": [
        {
          "id": "msg_67890",
          "role": "user",
          "content": "Hello, I'm having trouble with...",
          "createdAt": "2023-10-27T14:25:00Z"
        },
        {
          "id": "msg_67891",
          "role": "support_agent",
          "content": "Hi there, I can help with that. Could you please provide...",
          "createdAt": "2023-10-27T14:30:00Z"
        }
      ]
    }
  ]
}

Troubleshooting

• Incorrect JSON Format: Ensure that the JSON response from your endpoint matches the format specified in this article.

• Invalid URL: Ensure that the URL you provide is a publicly accessible endpoint.

• Authentication: This feature does not currently support authenticated endpoints.