How to call a customer

This endpoint allows you to initiate an outbound voice call between a dealership user and a customer.

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/{departmentUUID}/customer/{customerUUID}/twilio/callContact

Parameters

Required path parameters:

Parameter Name	Value	Description
departmentUUID	string	Unique identifier of dealer department
customerUUID	string	Unique identifier of customer

Authorization

This request requires the following authorization scopes:

Scope	Level	Description
call.create	DealerDepartment	Authorizes client to initiate an outbound call from a dealership user to provided customer

Important Notes

Prerequisites

The following requirements must be met for this API to work correctly:

User Authority Required:

• The user (identified by userUUID) must have the voice.call authority enabled in myKaarma settings. If this authority is not present, the request will fail with error code MISSING_VOICECALL_AUTHORITY.

Call Recording Requirements: For the call to be recorded, all of the following conditions must be met:

1. The dealership must have the messaging.call.record.enable setting enabled
2. The user must have the voice.record authority
3. The user must not have the communication.outbound.call.greeting.disable authority

If any of these conditions are not met, the call will proceed without recording.

Request Body

The request body contains the following properties:

Property Name	Type	Description
userUUID	string	Required. Unique identifier of the user initiating the call.
party1Number	string	Optional. The phone number of the first party (i.e., the dealership user) in E.164 format or 10-digit US format. If not provided or empty, the system will automatically use the phone number associated with the user's profile (identified by userUUID). If no phone number is found for the user, the request fails with error code MISSING_PHONE_NUMBERS.
party2Number	string	Optional. The phone number of the second party (i.e., the customer) in E.164 format or 10-digit US format. See Phone Number Validation below for details on validation and fallback behavior.

Phone Number Validation

The party2Number is validated to ensure it belongs to the customer and is marked as ok to call. The validation follows this logic:

1. Valid Number: If the provided party2Number matches one of the customer's phone numbers and has okToCall set to true, the call proceeds normally.

2. Automatic Fallback: If the provided party2Number is empty, invalid, or not marked as okToCall, the system will automatically search for an alternative phone number from the customer's profile:

   • First, it looks for a phone number marked as isPreferred with okToCall set to true
   • If no preferred number is found, it uses any phone number with okToCall set to true
   • If a fallback number is found, the system automatically updates party2Number and returns a warning with code INVALID_COMMUNICATION_VALUE and description stating the fallback number used.

3. Validation Failure: If no valid okToCall phone number is found for the customer, the request fails with error code INVALID_COMMUNICATION_VALUE.

Examples

Example 1: Initiating a Call

This example demonstrates how to initiate a call between a dealer associate and a customer.

curl --location --request POST 'https://api.mykaarma.com/communications/department/{{departmentUUID}}/customer/{{customerUUID}}/twilio/callContact' \
--header 'accept: application/json' \
-u "{{username}}:{{password}}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "userUUID": "{{userUuid}}",
    "party1Number": "{{party1Number}}",
    "party2Number": "{{party2Number}}"
}'

Response

{
    "sid": "string",
    "messageUUID": "string",
    "status": "SUCCESS" | "FAILURE",
    "errors": [
        {
            "errorCode": "string",
            "errorDescription": "string",
            "errorUID": "string"
        }
    ],
    "warnings": [
        {
            "warningCode": "string",
            "warningDescription": "string"
        }
    ]
}

Response Fields

Field	Type	Description
sid	string	The unique identifier (SID) for the call session, as returned by Twilio (our third-party provider).
messageUUID	string	The unique identifier for the message created in the myKaarma system for this call.
status	string	The status of the call initiation ("SUCCESS" or "FAILURE").
errors	array	List of errors, if any occurred.
warnings	array	List of warnings, if any occurred.

Common Error Codes

Error Code	Description
MISSING_UUIDS	The departmentUUID parameter is missing or null.
MISSING_CUSTOMER_UUID	The customerUUID parameter is missing or null (for non-support calls).
MISSING_VOICECALL_BODY	The request body is missing or null.
MISSING_PHONE_NUMBERS	The party1Number is missing or empty and no phone number found for the user with the passed userUUID.
MISSING_VOICECALL_AUTHORITY	The user does not have the voice.call authority enabled in myKaarma settings.
INVALID_CUSTOMER	Unable to fetch customer data for the provided customerUUID.
INVALID_COMMUNICATION_VALUE	The provided party2Number is not found or not marked as okToCall, and no alternative valid phone number is available for the customer.

Common Warning Codes

Warning Code	Description
INVALID_COMMUNICATION_VALUE	The provided party2Number was empty, not found, or not marked as okToCall. The system automatically used an alternative phone number from the customer's profile. The warning description will include the phone number that was used instead.