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.
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 8 months ago