How to send a system notification with notifier pop

This endpoint allows you to post a system notification within a customer conversation and pop the myKaarma notifier for dealership users. System notifications are not sent to the end customer; they are only shown within the customer conversation in myKaarma. Unlike an internal note, a system notification is created automatically by a system (isManual: false) rather than by a user.

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.

tip

A system notification is only saved in the conversation unless you also pass notificationAttributes. To pop the notifier for dealership users, set threadOwnerNotifierPop and/or additionalNotifierNotificationDAUUIDs as described below.

Request

HTTP request

POST  https://api.mykaarma.com/communications/department/{departmentUUID}/user/{userUuid}/customer/{customerUuid}/message

Parameters

Required path parameters:

Parameter Name	Value	Description
`departmentUUID`	`string`	Unique identifier of dealer department
`userUuid`	`string`	Unique identifier of the user on behalf of whom the notification is posted. Pass the literal value `DEFAULT` to use the department's Default DealerAssociate.
`customerUuid`	`string`	Unique identifier of customer whose conversation the notification is posted in

Authorization

This request requires the following authorization scopes:

Scope	Level	Description
`message.create`	`DealerDepartment`	Authorizes client to create system notifications for the provided user's dealer department

Request Body

The request body contains the following main objects:

`messageAttributes` (Required)

Property Name	Type	Description
`body`	`string`	Text of the system notification
`type`	`string`	Set to `NOTE`
`protocol`	`string`	Set to `NONE`. No customer phone number or email is needed for this protocol.
`isManual`	`boolean`	Set to `false` for a system notification
`showInCustomerConversation`	`boolean`	Default: `true` Whether the notification is shown in the customer conversation
`updateThreadTimestamp`	`boolean`	Default: `false` Set to `true` to move the customer conversation to the top of the list
`updateTotalMessageCount`	`boolean`	Default: `true` Whether the notification counts toward the conversation's total message count

`notificationAttributes` (Optional)

Controls which dealership users get the notifier pop. If this object is not passed, the notification is saved in the conversation but no user is notified.

Property Name	Type	Description
`threadOwnerNotifierPop`	`boolean`	Set to `true` to pop the notifier for the user who owns the customer conversation
`additionalNotifierNotificationDAUUIDs`	`array`	List of DealerAssociate UUIDs to pop the notifier for. These are DealerAssociate UUIDs, not user UUIDs.
`internalSubscribersNotifierPop`	`boolean`	Set to `true` to pop the notifier for internal subscribers of the conversation
`externalSubscribersNotifierPop`	`boolean`	Set to `true` to pop the notifier for external subscribers of the conversation
`sendPhoneNotification`	`boolean`	Default: `false` Set to `true` to also send a push notification to the myKaarma mobile app

`messageSendingAttributes` (Optional)

Property Name	Type	Description
`sendSynchronously`	`boolean`	Default: `false` Set to `true` to save the notification before the API returns. When `false`, the notification is queued and saved in the background.

Example

Post a system notification and pop the notifier

curl --location --request POST 'https://api.mykaarma.com/communications/department/{{departmentUUID}}/user/{{userUuid}}/customer/{{customerUuid}}/message' \
--header 'accept: application/json' \
-u "{{username}}:{{password}}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "messageAttributes": {
        "body": "Customer opted out of text messages",
        "type": "NOTE",
        "protocol": "NONE",
        "isManual": false,
        "showInCustomerConversation": true,
        "updateThreadTimestamp": false
    },
    "messageSendingAttributes": {
        "sendSynchronously": true
    },
    "notificationAttributes": {
        "threadOwnerNotifierPop": true,
        "additionalNotifierNotificationDAUUIDs": ["{{dealerAssociateUuid}}"],
        "sendPhoneNotification": true
    }
}'

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",
  "requestUUID": "request_uuid",
  "status": "SUCCESS",
  "errors": [],
  "warnings": []
}

Failure

If the request fails, the API returns a 400 BAD REQUEST 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": []
}

Error Codes

The following error codes may be returned:

Error Code	Description
`MISSING_MESSAGE_ATTRIBUTES`	Message attributes are missing in the request.
`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.
`INVALID_CUSTOMER`	The provided customer UUID is invalid for the department.
`INVALID_USER`	The provided user UUID is not a valid DealerAssociate of the department.
`INTERNAL_SERVER_ERROR`	An unexpected error occurred on the server.

Request​

HTTP request​

Parameters​

Authorization​

Request Body​

messageAttributes (Required)​

notificationAttributes (Optional)​

messageSendingAttributes (Optional)​

Example​

Post a system notification and pop the notifier​

Response​

Success​

Failure​

Error Codes​