Save number and Incoming lead
When a call with a number with which there is no linked entity in the system happens
- a notification about this call can be created, with a link to create contact with this number.
- an incoming lead can be created
Save number
In the call notification, the link requests a method url contacts/add that takes the phone number as an argument in order to create a client with this number. This is implemented in the frontend of the integration.
Method
URL contacts/add
Parameter
| Parameter | Description |
| phone | The phone number for which we want to add a contact |
Example
https://subdomain.kommo.com/contacts/add?phone=+18305703077
The result is a window to create a new contact.
To process saving contact, you can use the same code we used to provide a notification, and add the part where the call comes from an unknown number.
add_call_notify = function(data){
var w_name = self.i18n('widget').name,
lang = self.i18n('settings'),
n_data = {
from: data.from,
to: data.to,
duration: data.duration,
link: data.link,
text: w_name + ': ' + data.text,
date: Date.now(),
element: data.element
};
/* Check if there is an incoming caller’s contact id in the system */
if (n_data.element.id > 0){
//If there is an already existing id , create a link for this contact in Kommo
text = 'Call from '+n_data.element.name+' Go to the contact card';
n_data.text = text;
n_data.from = data.from;
if (n_data.from.length < 4){
//Check for an internal number
n_data.header = 'Internal number: '+data.from+';
}
else {
n_data.header = 'Incoming call: '+data.from+';
}
} else { //If the ID does not exist, we form a link to create a new contact
text = '<a href="/contacts/?phone=' + data.from + '">Create contact</a>';
n_data.text = text;
n_data.header = 'Incoming call ' + data.from;
}
APP.notifications.add_call(n_data);
};Create incoming lead
In Kommo, there is the «Incoming lead» entity that initiates contact through managers’ connected channels like VoIP integrations which are considered as a Lead source.
Incoming calls from unknown numbers should appear in the “Incoming leads” column as a card with the phone number, the manager who took the call, the call date and time, the duration of the call with a link to download the call recording, and by pressing on the player icon manager can listen to it.
When adding the incoming lead, a call status and result can be specified. The manager also can add a task at a specified time either in the call result window if it’s implemented or in the incoming lead’s feed.
Within the creation of the incoming lead from a call, the contact and company will be ready to be automatically added to the system and linked to the incoming lead. That means they will be shown in gray color. Also the call and the task will be added to the system and linked to the generated (incoming) lead.
When the manager accepts the incoming lead, either by choosing to accept it or by dragging and dropping it in one of the pipeline’s lead stages, a lead and a contact or a company are created.
If the incoming lead is declined, it will disappear from the “Incoming leads”, all information about the call will disappear as well, that includes the lead, the call, the contact, the company and the task.
Example of adding calls to the “Incoming leads”
Method URL
POST /api/v4/leads/unsorted/sip
Authorization type
OAuth 2.0 with Access Token. Review our Step-by-step Example.
Headers
Content-Type: application/json
Example of a request body
[
{
"request_id": "123",
"source_name": "BB Co.",
"source_uid": "a1fee7c0fc436088e64ba2e8822ba2b3",
"pipeline_id": 5597036,
"created_at": 1666110634,
"_embedded": {
"leads": [
{
"name": "Tech maintenance",
"price": 5500,
"_embedded": {
"tags": [
{
"id": 263809
}
]
}
}
],
"contacts": [
{
"name": "TECH man"
}
],
"companies": [
{
"name": "BB Co."
}
]
},
"metadata": {
"uniq": "a1fe231cc88e64ba2e8822ba2b3eqeq",
"duration": 70,
"service_code": "CkAvbEwPam6sad",
"link": "https://file-examples.com/wp-content/uploads/2017/11/file_example_MP3_700KB.mp3",
"phone": 1234567891,
"called_at": 1666110534,
"from": 8375357,
"call_result":"Sale on Monday",
"call_status":4,
"is_call_event_needed": true,
"category": "sip"
}
}
]
Parameters
| Parameter | Type | Description |
| request_id | string | The field that will be returned unchanged in the response and will not be saved. Is not a mandatory field |
| source_name required | string | Incoming lead source name |
| source_uid required | string | Incoming lead source UID. The integration should generate it. |
| pipeline_id | int | The ID of the pipeline the incoming lead will be added to. If this parameter is not sent then the incoming lead will be added to the first pipeline |
| created_at | timestamp | Incoming lead creation date in the format of Unix Timestamp |
| incoming_lead_info | array | An array that contains an incoming lead data |
| _embedded required | array | An array that contains created entities elements data. It’s required because when an incoming lead is accepted, the corresponding element of the entity will be created. |
| _embedded/leads | array | An array that contains the data for creating a new lead. It may contain all parameters and custom fields that are available for “Leads” in the account. |
| _embedded/contacts | array | An array that contains the data for creating a new contact. It may contain all parameters and custom fields that are available for “Contacts” in the account. |
| _embedded/companies | array | An array that contains the data for creating a new company. It may contain all parameters and custom fields that are available for “Companies” in the account. |
| metadata/is_call_event_needed | boolean | A boolean indicates if the call event will be added to the entity card. “true” for yes. |
| metadata/uniq | int | Identifier for the event |
| metadata/duration required | int | Call duration |
| metadata/service_code required | string | Service provider code |
| metadata/called_at required | timestamp | Call date in the format of Unix Timestamp |
| metadata/link required | string | A link to the call recording |
| metadata/phone required | string | The phone number with which the call happened |
| metadata/uniq required | string | Unique call code |
| metadata/from required | string | Call initiator. If you add the manager id, the manager name will be shown |
| metadata/call_status | int | The status of the call |
| metadata/call_result | string | Note about the call |
| metadata/category | string | “sip” for call |
Response example
{
"_total_items": 1,
"_embedded": {
"unsorted": [
{
"uid": "308be4de3c941e759612f831f523fe7c553922785384767544ab169182b8",
"account_id": 30285908,
"request_id": "123",
"_links": {
"self": {
"href": "https://subdomain.kommo.com/api/v4/leads/unsorted/4ab169182b8"
}
},
"_embedded": {
"contacts": [
{
"id": 9013064,
"_links": {
"self": {
"href": "https://subdomain.kommo.com/api/v4/contacts/9013064"
}
}
}
],
"leads": [
{
"id": 6872526,
"_links": {
"self": {
"href": "https://subdomain.kommo.com/api/v4/leads/6872526"
}
}
}
],
"companies": []
}
}
]
}
}