Call logging

Our API provides the opportunity to add information to a lead, customer, contact or company. Events in the cards are displayed in the feed and include information about tasks, chat and calls. If the call event has a link to the call recording file, a player will be added to the call note to play this recording.
foto

Call logging algorithm

You must know that when using logging methods, the manager can select which entity they want to attach to the call. If they do not choose, Kommo will find a contact or company with the specified phone number, as well as all related entities, and add a call to one of them in the following order:

  1. If the contact/company has one active lead and there are no related customers, then the call will be added to the lead.
  2. If the contact/company has one customer and there are no active leads, then the call will be added to the customer.
  3. If the contact/company has more than one active lead/customer or there are no related entities, the call will be added to the contact/company card.

Now let’s learn in detail how to use the logging method correctly.

Call logging API method

This method allows you to add calls to cards one by one or in batches. When adding calls, the algorithm described above will be used. If there is a card with the phone number mentioned in the request, the call will be added. If no entity with a number was found, the manager is given the option to save the number and then to add a note about the call. If the manager chooses not to, the call will not be added.

Method URL

POST /api/v4/calls/

Authorization type

OAuth 2.0 with Access Token. Review our Step-by-step Example.

Headers

Content-Type: application/json

Example of a request body

[
    {
     "uniq": "394427aaf821879e29efbc4eb78er22171530",
     "phone": "18305803077",
     "source": "kommo_custom_widget",
     "created_at": 1662544423,
     "created_by": 8375357,
     "duration": 20,
     "call_status": 2,
     "direction": "inbound",
     "link": "https://file-examples.com/wp-content/uploads/2017/11/file_example_MP3_1MG.mp3",
     "responsible_user_id": 8375357
   },
   {
     "uniq": "394427aaf821879e29efbc4eb78er22171525",
     "phone": "18305803077",
     "source": "kommo_custom_widget",
     "created_at": 1662544423,
     "created_by": 8375357,
     "duration": 105,
     "call_status": 4,
     "call_result": "Agreed on the price",
     "direction": "inbound",
     "link": "https://file-examples.com/wp-content/uploads/2017/11/file_example_MP3_1MG.mp3",
     "responsible_user_id": 8375357
   },
    {
      "uniq": "394427aaf821879e29efbc4eb78er22171525",
      "phone": "18305803078",
      "source": "kommo_custom_widget",
      "created_at": 1662544423,
      "created_by": 0,
      "duration": 0,
      "call_status": 6,
      "direction": "outbound",
      "responsible_user_id": 8375357
    }
]

Please! Pay attention to the entered data! The request body should be in array type. This means that calls are added as a list even if it’s just one call! The “phone” body parameter should be saved to a contact in the Kommo account, and responsible_user_id and created_by should also be the identifiers for users in the Kommo account.

foto

Body parameters

Parameter Type Description
phone required string External phone number
direction required string Type of call (inbound: incoming from customer to manager, outbound: outgoing from manager to customer)
uniq string Unique call code
duration string Duration of the call in seconds
source string The code of the widget or service through which the call was made
call_status int The status of the call
call_result string Call result: text added by the manager when saving a note about the call
link string Link to the call recording audio file
created_at timestamp Date and time when the call note was created, passed to Unix Timestamp
updated_at timestamp Date and time when the call note was updated, passed to Unix Timestamp
created_by int ID of the user who created the call note. If it’s not explicitly specified in the request, the account administrator’s code is entered by default. This parameter is responsible for displaying the user name in the blocks from whom/to whom the call was made.
updated_by int ID of the user who updated the call note.
responsible_user_id int ID of the user responsible for the call. If this parameter is specified, the responsible user will be able to perform an action with a note (for example, delete it)

Call status

Type Description
1 Left a voice message
2 Call back later
3 Not available
4 Spoke with client
5 Wrong number
6 No answer
7 Number is busy

Example of response

{
    "_total_items": 2,
    "errors": [
        {
            "title": "Entity not found",
            "status": 263,
            "detail": "Entity not found",
            "request_id": "2"
        }
    ],
    "_embedded": {
        "calls": [
            {
                "id": 17613096,
                "entity_id": 5760184,
                "entity_type": "contact",
                "account_id": 30285908,
                "request_id": "0",
                "_embedded": {
                    "entity": {
                        "id": 5760184,
                        "is_deleted": false,
                        "is_unsorted": false,
                        "_links": {
                            "self": {
                                "href": "https://subdomain.kommo.com/api/v4/contacts/5760184"
                            }
                        }
                    }
                }
            },
            {
                "id": 17613098,
                "entity_id": 5760184,
                "entity_type": "contact",
                "account_id": 30285908,
                "request_id": "1",
                "_embedded": {
                    "entity": {
                        "id": 5760184,
                        "is_deleted": false,
                        "is_unsorted": false,
                        "_links": {
                            "self": {
                                "href": "https://subdomain.kommo.com/api/v4/contacts/5760184"
                            }
                        }
                    }
                }
            }
        ]
    }
}

Response parameters

Parameter Description
_embedded An array containing information about the successfully added calls
_embedded[calls] Array with successfully added calls
_embedded[calls][0][id] Unique identifier of the call note
_embedded[calls][0][entity_id] Unique identifier of the entity to which the call was attached
_embedded[calls][0][entity_type] Type of the entity to which the call was attached
_embedded[calls][0][account_id] ID of the account in which the call was added
_embedded[calls][0][request_id] Index of the request in the input array
_embedded[calls][0][_embedded] Array containing information about the created objects
_embedded[calls][0][entity][0][id] ID of the created call entity
_embedded[calls][0][entity][0][_links[self][href] URL of API GET request of the created call object
_embedded[errors] Array with calls that could not be added
_embedded[errors][0][title] Error Message
_embedded[errors][0][code] Error codes
_embedded[errors][0][detail] Details about the error
_embedded[errors][0][request_id] Index of the request in the input array