How to post an internal note for a customer

This endpoint allows you to post an internal note within a customer conversation. These notes are not visible to the end customer; they are only shown within the customer conversation in myKaarma. There's also a functionality to tag users or user groups to notify them, but that is out of scope of this documentation at the moment.

To use this endpoint, you first need your credentials. If you don't already have one, please head over to the Authentication and Authorization page to see how you can request for credentials from us.

Request

HTTP request

POST  https://api.mykaarma.com/communications/department/{department_uuid}/customer/{customer_uuid}/message

Parameters

Required path parameters:

Parameter Name	Value	Description
department_uuid	string	Unique identifier of dealer department
customer_uuid	string	Unique identifier of customer

Authorization

This request requires the following authorization scopes:

Scope	Level	Description
message.create	DealerDepartment	Authorizes client to create internal notes for the provided user's dealer department

Request Body

The request body contains the following main objects:

editor (Required)

The user on behalf of whom the internal note gets posted.

Property Name	Type	Description
uuid	string	Unique identifier of the user
departmentUuid	string	Unique identifier of the department
type	string	Type of editor, USER in this case

messageAttributes (Required)

Property Name	Type	Description
body	string	JSON string containing the message content. Structure: {"text":[{"type":{"code":"PLAIN_TEXT","value":"text/plain"},"value":"your message here"}],"version":0,"previewText":"your message here","annotations":[]}
type	string	Message type (set to NOTE for internal note)
protocol	string	Protocol (set to NONE for internal note)
isManual	boolean	Pass it as true
updateThreadTimestamp	boolean	Pass it as true
updateTotalMessageCount	boolean	Pass it as true
showInCustomerConversation	boolean	Pass it as true
messageTags	array	Array of message tags

messageSendingAttributes (Optional)

Property Name	Type	Description
addSignature	boolean	N/A, set to false
sendSynchronously	boolean	Whether to send synchronously
overrideOptoutRules	boolean	N/A, set to false

internalCommentAttributes (Optional)

Property Name	Type	Description
usersToNotify	array	List of UUIDs of users to notify
usersSubscribed	array	List of subscribed users
usersUnSubscribed	array	List of unsubscribed users

Example

Post an Internal Note

curl --location 'https://api.mykaarma.com/communications/department/{department_uuid}/customer/{customer_uuid}/message' \
--header 'accept: application/json' \
--header 'authorization: <your-credentials>' \
--header 'Content-Type: application/json' \
--data '{
    "editor": {
        "uuid": "user_uuid",
        "departmentUuid": "department_uuid",
        "type": "USER"
    },
    "messageAttributes": {
        "body": "{\"text\":[{\"type\":{\"code\":\"PLAIN_TEXT\",\"value\":\"text/plain\"},\"value\":\"test internal\"}],\"version\":0,\"previewText\":\"test internal\",\"annotations\":[]}",
        "type": "NOTE",
        "protocol": "NONE",
        "isManual": true,
        "updateThreadTimestamp": true,
        "updateTotalMessageCount": true,
        "showInCustomerConversation": true,
        "messageTags": []
    },
    "messageSendingAttributes": {
        "addSignature": false,
        "sendSynchronously": true,
        "overrideOptoutRules": false
    },
    "internalCommentAttributes": {
        "usersToNotify": [],
        "usersSubscribed": [],
        "usersUnSubscribed": []
    }
}'

Response

Success

If the request is successful, the API returns a 200 OK status code with a JSON response containing the details of the created message.

{
  "messageUUID": "message_uuid",
  "customerUUID": "customer_uuid",
  "status": "SUCCESS",
  "errors": [],
  "warnings": [
    {
      "warningCode": "WARNING_CODE",
      "warningDescription": "Warning description"
    }
  ]
}

Failure

If the request fails, the API returns a 400 BAD REQUEST, 501 NOT IMPLEMENTED, or 500 INTERNAL SERVER ERROR status code with a JSON response containing a list of errors.

{
  "status": "FAILURE",
  "errors": [
    {
      "errorCode": "ERROR_CODE",
      "errorDescription": "Error description"
    }
  ],
  "warnings": [
    {
      "warningCode": "WARNING_CODE",
      "warningDescription": "Warning description"
    }
  ]
}

Error Codes

The following error codes may be returned:

Error Code	Description
MISSING_MESSAGE_ATTRIBUTES	Message attributes are missing in the request.
INVALID_USER	Editor details are invalid, or users to notify have invalid fields.
MISSING_MESSAGE_TYPE	The type field is missing in message attributes.
MISSING_MESSAGE_PROTOCOL	The protocol field is missing in message attributes.
MISSING_IS_MANUAL	The isManual field is missing.
MISSING_MESSAGE_BODY	The message body is empty and no attachments are provided.
MISSING_FREEMARKER_METADATA	Freemarker metadata is missing for a freemarker message.
INVALID_CUSTOMER	The provided customer UUID is invalid.
NOT_IMPLEMENTED	The requested functionality (e.g., non-NONE protocol for NOTE type) is not implemented.
INTERNAL_SERVER_ERROR	An unexpected error occurred on the server.