How to send a vehicle service chat summary event

This document is designed to help you understand how you can send a vehicle service chat summary event to myKaarma.

To perform these actions, you first need your credentials. If you don't already have them, head over to the Authentication and Authorization page to see how you can request credentials from us. The process of sending a vehicle service chat summary event is listed below.

Authorization

Parameter Name	Description	Required
{{basic_auth_token}}	Authorization: Base64 encoded string using Service Subscriber Username and password	Yes

Scope

This process requires the following authorization scopes:

Scope	Level	Description
spd.events.vehicleservicechat.write	Dealer	Authorizes client to send a vehicle service chat summary event for provided dealer

Endpoint

curl -X POST "https://api.mykaarma.com/service-pre-diag/third-party-events/vehicle-service-chat/v1"
-H "Authorization: {{basic_auth_token}}"
-H "Content-Type: application/json"
-d '{
    "customer_name" : "string",
    "vin" : "string",
    "chat_code" : "string",
    "vehicle_uuid" : "string",
    "appointment_uuid" : "string",
    "dealer_uuid" : "string",
    "event_timestamp" : long,
    "summary" : "string",
    "escalation_flag" : boolean,
    "line_items": [
        {
            "description" : "string",
            "payable" : boolean
        }
    ],
    "transcript": [
        {
            "customer":"string",
            "assistant":"string"
        }
    ],
    "media": [
        {
            "type": "image",
            "url": "string"
        },
        {
            "type": "video",
            "url": "string"
        }
    ]
}'

Response

{
  "errors": [
    {
      "errorCode": "string",
      "errorMessage": "string"
    }
  ],
  "warnings": [
    {
      "warningCode": "string",
      "warningMessage": "string"
    }
  ],
  "requestId": "string"
}

Request Body

There is no fixed schema for the request body. The endpoint accepts any valid JSON object, which should be sent as a stringified JSON in the body of the request.

Note

The request body schema must be mutually agreed upon between the third party and myKaarma prior to hitting this endpoint. The request body must contain the following fields:

Parameter	Description
Unique dealer identifier	Unique identifier of the dealer in myKaarma’s system or the corresponding identifier used in the third-party's system. In cases where the third-party-specific identifier is used, a mapping between the third-party's and myKaarma's identifiers must be shared with myKaarma in advance to ensure correct association and processing of events
Event timestamp	Timestamp (In milliseconds since Unix epoch (UTC)) when event was created. This is defaulted to timestamp when the event was received by myKaarma

Response Object Explanation

{{errors}} An array of error objects detailing issues encountered during processing vehicle service chat summary event.

{{warnings}} An array of warning objects providing non-critical alerts encountered during processing vehicle service chat summary event.

{{errors.errorCode}} Code indicating the specific error encountered during processing vehicle service chat summary event; refer to the API reference for a list of possible error codes.

{{errors.errorTitle}} Title describing the specific error encountered during processing vehicle service chat summary event; refer to the API reference for detailed descriptions.

{{errors.errorMessage}} Detailed message describing the specific error encountered during processing vehicle service chat summary event; refer to the API reference for more information.

{{requestId}} Unique UUID issued by myKaarma for identifying the event.

Process

This is an asynchronous endpoint that exclusively accepts events from third parties with an active integration contract with myKaarma. Upon receiving a request, the system performs the following steps in the given sequence:

STEP 1: Performs basic authentication using the {{basic_auth_token}} passed in the request

STEP 2: Identifies the third-party source of the event by the username extracted from {{basic_auth_token}} passed in the request, if the event source is not a valid third party having an active integration contract with myKaarma then the event is discarded and the error INVALID_EVENT_SOURCE is thrown

STEP 3: Persists the raw event data in the database

STEP 4: Responds with a 200 OK back to client (200 OK response acknowledges receipt and not complete processing of the event)

STEP 5: Event validation and transformation rules are applied asynchronously, based on the predefined configurations established for the respective third-party integration

Note

Event validation and transformation rules are third-party-specific and are defined based on mutual discussions and agreement between the third party and myKaarma prior to integration.