Guides
HomeAPI ReferenceGuidesChangelogKarhoo.com

Introduction to Support Framework

Support Framework is a part of the Karhoo system that enables users to create and manage support tickets. It exposes a public API, so it can be integrated with either a demand partner’s custom CRM or a helpdesk software such as e.g. Zendesk. The main goal of the Support Framework is to provide an efficient communication channel directly between demand partners and supply partners so that every issue related to a trip can be solved in the optimal time. All trip details are attached to the support ticket automatically using Karhoo data.

Suggest Edits

Authorisation

The prerequisite for using this authorisation grant is a valid Karhoo account (registered by a Karhoo representative). Once the account is created, the user can then log in to the Partner Portal and issue an API Key, which can be used directly in API calls as an authorisation grant. In order to authorise an API call, the Authorization header must be added to the request:

HTTP GET https://rest.karhoo.com/v1/support/tickets
Authorization: ApiKey <your-api-key>

You can find more details about this approach in this section.


Create a ticket

Endpoints

Two endpoints can be used to create a support ticket in the Karhoo Support Framework. The only difference between the endpoints is path params - {partnerTripId} is an ID used by a demand partner and {tripId} is the one used by Karhoo (UUID).

# with Karhoo Trip UUID
HTTP POST https://rest.karhoo.com/v1/support/trips/{tripId}/tickets

# with Partner's Trip ID
HTTP POST https://rest.karhoo.com/v1/support/demand/trips/{partnerTripId}/tickets

Payload

Payload is the same for both endpoints:

  • subject - string, required; Subject of the support ticket.
  • comment - string, required; The ticket’s description.
  • contactEmail - string, optional; An email address that will be used to exchange messages within the support ticket. If not provided, the support contact email configured at Karhoo will be used.
  • attachments - array of strings, optional; An array of resource tokens obtained from uploading the attachment in a separate request - check the details below.

Attachments

In order to add attachments while creating a support ticket, they must be uploaded to a file storage first. Once uploaded, the returned resourceToken can be used in the optional attachments field.

HTTP POST https://rest.karhoo.com/v1/support/upload-attachment

Request payload:
{
  file:  <binary>
}
  
Successful response:
{
  resourceToken: "c0zifNtV7heNI2eYrncPbJods"
}

Communication within a ticket

Once a ticket is created, the request will be forwarded directly to the fleet. Further communication will take place via email. Trip's details such as ID, location, date and time will be provided in the ticket as a table together with the subject and the comment. When the fleet replies to the received message, the demand partner will receive messages to the email address provided in the HTTP request's body as contactEmail or to the default address configured in Karhoo in case contactEmail was not provided. The fleet will not see the partner's email address, as all communication will be passed between the parties by Karhoo.

Example

Karhoo Trip UUID: a9eaaeb3-660b-42c3-930d-20150fe46e9a

ApiKey: XYZ1234

HTTP POST https://rest.karhoo.com/v1/support/trips/a9eaaeb3-660b-42c3-930d-20150fe46e9a/tickets
Authorization: ApiKey XYZ1234

{
  subject: "Trip information update",
  comment: "Please update the information. Passenger details have been updated.",
  contactEmail: "[email protected]",
  attachments: ["c0zifNtV7heNI2eYrncPbJods"]
}

Note: Each attachment can be added in only one support ticket. Attachments cannot be reused.

The email message sent from the Support Framework will look as below:


Partner Portal

If you don't need to call the Support Framework API directly, it's highly recommended to use the Partner Portal instead. It provides all the above and a lot of other features wrapped in a user-friendly UI.


Updated 7 months ago