Adding calls

In this section, we will describe the method to add calls to the account

Common information

For the call adding method, the system automatically finds a contact or company with the specified phone number as well as all linked leads and customers and adds the call into the entity card based on the following algorithm:

  • if a contact/company has one active lead and no linked customers, the call will be added to the lead card
  • if a contact/company has one linked customer and no linked active leads, the call will be added to the customer card
  • if a contact/company has more than one active lead/linked customer or there are no linked entities at all, the call will be added into the contact/company card
  • the search is performed by the last 10 digits of the number

Adding calls

Method

POST /api/v4/calls

Description

This method allows adding multiple calls into entity cards.
Calls are added in the correspondence to the algorithm described above.
If the card that follows the algorithm terms exists in the account, the call will be added immediately.
If there’s no entity with the specified phone number, the call will not be added.

Limitations

The method is available in correspondence to the user rights.

Request header

Content-Type: application/json

Request parameters

Parameter Data type Description
direction string Call direction: inbound, outbound. Is a mandatory parameter
uniq string Unique call identifier. Is not a mandatory parameter
duration int Call duration in seconds. Is a mandatory parameter
source string Call source. Is a mandatory parameter
link string Link to the call recording. Is not a mandatory parameter
phone string The phone number that will be searched. Is a mandatory parameter
call_result string Call result. Is not a mandatory parameter
call_status int Call status. Available statuses: 1 – left a message, 2 – call back later, 3 – not available, 4 – had a conversation, 5 – invalid phone number, 6 – no connection, 7 – the line is busy. Is not a mandatory parameter
responsible_user_id int ID of the user responsible for the call
created_by int ID of the user who created the call
updated_by int ID of the user who edited the call last
created_at int Call creation date in the format of Unix Timestamp
updated_at int Call edit date in the format of Unix Timestamp
request_id string Field that will be returned unchanged in the response and will not be saved. Is not a mandatory parameter

An example of the request


[
  {
    "duration": 10,
    "source": "example_integration",
    "phone": "+14155551234",
    "link": "https://example.com/audio.mp3",
    "direction": "inbound",
    "call_result": "Had a conversation",
    "call_status": 4
  }
]

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Request successful
401 The user is not authorized
400 Invalid data are given. Details are available in the request-response

Response parameters

The method returns a collection of added calls. The properties of the call are listed below.

Parameter Data type Description
id int ID of the added note
entity_id int ID of the entity the call is added into
entity_type int Type of the entity the call is added into
account_id int ID of the account the call is added into
request_id string The string that’s passed in the request or an index number if none passed
_embedded object Embedded entities data
_embedded[entity] object Model of the entity the call is added to
_embedded[entity][id] int ID of the entity the call is added to

Response example


{
    "_total_items": 1,
    "errors": [],
    "_embedded": {
        "calls": [
            {
                "id": 37512063,
                "entity_id": 11070881,
                "entity_type": "contact",
                "account_id": 28805383,
                "request_id": "0",
                "_embedded": {
                    "entity": {
                        "id": 11070881,
                        "_links": {
                            "self": {
                                "href": "https://example.kommo.com/api/v4/contacts/11070881"
                            }
                        }
                    }
                }
            }
        ]
    }
}