### Private Integration Setup - Fetch Leads

Source: https://context7.com/context7/developers_kommo_com-docs-kommo-for-developers/llms.txt

Demonstrates how to set up a private integration using a long-lived token and fetch lead data from the Kommo API.

```APIDOC
## GET /api/v4/leads

### Description
Fetches a list of leads from the Kommo CRM account.

### Method
GET

### Endpoint
/api/v4/leads

### Parameters
#### Query Parameters
- **access_token** (string) - Required - The long-lived access token for authentication.

### Request Example
```javascript
const KOMMO_DOMAIN = 'yoursubdomain.kommo.com';
const ACCESS_TOKEN = 'your_long_lived_token_here';

fetch(`https://${KOMMO_DOMAIN}/api/v4/leads`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${ACCESS_TOKEN}`,
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data._embedded.leads))
.catch(error => console.error('Error:', error));
```

### Response
#### Success Response (200)
- **_embedded** (object) - Contains the list of leads.
  - **leads** (array) - An array of lead objects.
    - **id** (integer) - The unique identifier for the lead.
    - **name** (string) - The name of the lead.
    - **price** (integer) - The price associated with the lead.

#### Response Example
```json
{
  "_embedded": {
    "leads": [
      {
        "id": 12345,
        "name": "John Doe",
        "price": 1000,
        "_links": {
          "self": {
            "href": "https://yoursubdomain.kommo.com/api/v4/leads/12345"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://yoursubdomain.kommo.com/api/v4/leads"
    }
  }
}
```
```

--------------------------------

### SalesBot Scenario Definition

Source: https://context7.com/context7/developers_kommo_com-docs-kommo-for-developers/llms.txt

An example structure for defining a SalesBot scenario, including triggers, messages, user input handling, and the invocation of custom actions.

```APIDOC
## SalesBot Scenario Definition

### Description
This outlines a typical Kommo SalesBot scenario configuration. It defines how the bot interacts with users, when it's triggered, how it collects information, and how it calls custom actions to perform specific tasks like checking order status.

### Method
Not Applicable (Configuration Object)

### Endpoint
Not Applicable

### Parameters
#### Request Body
- **name** (string) - Required - The name of the SalesBot scenario.
- **trigger** (object) - Required - Defines what initiates this scenario.
  - **type** (string) - Required - The type of trigger (e.g., 'message_contains').
  - **keywords** (array) - Required if type is 'message_contains' - An array of keywords that trigger the bot.
- **steps** (array) - Required - An array of objects defining the conversation flow.
  - **type** (string) - Required - The type of step (e.g., 'message', 'wait_for_input', 'custom_action').
  - **text** (string) - Required for 'message' type - The message text to send to the user.
  - **variable** (string) - Required for 'wait_for_input' type - The name of the variable to store user input in.
  - **action_id** (string) - Required for 'custom_action' type - The ID of the custom action to execute.
  - **parameters** (object) - Required for 'custom_action' type - An object mapping parameter names to their values (can use variables like {{variable_name}}).

### Request Example
```json
{
  "name": "Order Support Bot",
  "trigger": {
    "type": "message_contains",
    "keywords": ["order", "delivery", "tracking"]
  },
  "steps": [
    {
      "type": "message",
      "text": "I can help you check your order status. Please provide your order number."
    },
    {
      "type": "wait_for_input",
      "variable": "order_id"
    },
    {
      "type": "custom_action",
      "action_id": "check_order_status",
      "parameters": {
        "order_id": "{{order_id}}"
      }
    }
  ]
}
```

### Response
#### Success Response
No direct response to this definition, but successful definition allows the scenario to be activated.

#### Response Example
N/A
```

--------------------------------

### Kommo Widget Development Example - JavaScript

Source: https://context7.com/context7/developers_kommo_com-docs-kommo-for-developers/llms.txt

This snippet demonstrates the structure and functionality of a Kommo widget. It includes a manifest file (`manifest.json`) for configuration and a JavaScript file (`script.js`) for widget logic. The JavaScript code showcases initialization, binding actions to different CRM locations (like lead cards), handling settings, and interacting with Kommo's API to fetch data and display notifications.

```javascript
// Widget manifest.json
{
  "name": "widget.example",
  "version": "1.0.0",
  "title": "Example Integration",
  "description": "Sample widget demonstrating SDK capabilities",
  "settings": {
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  },
  "locations": [
    "leads/list",
    "leads/card",
    "contacts/card",
    "settings"
  ]
}

// script.js - Widget implementation
(function() {
  var widget = {
    callbacks: {
      // Widget initialization
      init: function() {
        console.log('Widget initialized');

        // Get current user info
        var currentUser = AMOCRM.constant('user');
        console.log('Current user:', currentUser);

        return true;
      },

      // Bind actions to widget locations
      bind_actions: function() {
        // Add custom button to lead card
        this.add_action('leads/card', function() {
          var leadId = AMOCRM.data.current_card.id;
          console.log('Lead card opened:', leadId);

          // Create custom button
          var $button = $('<button>')
            .addClass('button-input')
            .text('Check External System')
            .on('click', function() {
              widget.checkExternalSystem(leadId);
            });

          // Add button to card toolbar
          $('.card-toolbar').append($button);
        });

        return true;
      },

      // Settings page handler
      settings: function() {
        var $form = $('<div>')
          .append('<label>API Key:</label>')
          .append('<input type="text" name="api_key" class="text-input">');

        return $form;
      },

      // On settings save
      onSave: function() {
        var settings = {
          api_key: $('input[name="api_key"]').val()
        };

        // Save to widget settings
        return settings;
      }
    },

    // Custom method to check external system
    checkExternalSystem: function(leadId) {
      var self = this;

      // Get lead data from API
      AMOCRM.get('/api/v4/leads/' + leadId, {}, function(data) {
        console.log('Lead data:', data);

        // Call external API
        $.ajax({
          url: 'https://yourapi.com/check',
          method: 'POST',
          data: JSON.stringify({ lead: data }),
          contentType: 'application/json',
          success: function(response) {
            // Show notification in Kommo
            AMOCRM.notifications.show_message({
              text: 'External check completed: ' + response.status,
              header: 'Integration Status'
            });

            // Add note to lead
            self.addNote(leadId, 'External system check: ' + response.details);
          },
          error: function(error) {
            AMOCRM.notifications.show_message_error({
              text: 'Failed to check external system'
            });
          }
        });
      });
    },

    // Add note to entity
    addNote: function(entityId, text) {
      AMOCRM.post('/api/v4/leads/' + entityId + '/notes', {
        note_type: 'common',
        entity_id: entityId,
        parameters: {
          text: text
        }
      }, function(response) {
        console.log('Note added:', response);
      });
    }
  };

  return widget;
}());

```

--------------------------------

### POST /salesbot/check-order - SalesBot Action Handler

Source: https://context7.com/context7/developers_kommo_com-docs-kommo-for-developers/llms.txt

An example Express.js endpoint designed to handle a custom SalesBot action, querying an external system and responding to the SalesBot with actions and data.

```APIDOC
## POST /salesbot/check-order - SalesBot Action Handler

### Description
This endpoint serves as the backend logic for the 'check_order_status' custom SalesBot action. It receives order details from SalesBot, queries an external order system, and returns formatted messages, tasks, or custom field updates back to the SalesBot conversation.

### Method
POST

### Endpoint
/salesbot/check-order

### Parameters
#### Request Body
- **conversation_id** (string) - Required - The unique identifier for the ongoing conversation.
- **contact_id** (string) - Required - The identifier of the contact involved in the conversation.
- **order_id** (string) - Required - The order number provided by the user for status lookup.

### Request Example
(The actual request body is determined by the SalesBot scenario and the custom action definition)
```json
{
  "conversation_id": "conv_12345",
  "contact_id": "contact_67890",
  "order_id": "ABC-12345"
}
```

### Response
#### Success Response (200)
Returns a JSON object containing actions and/or custom field updates for the SalesBot to execute. The structure includes `conversation_id`, and an `actions` array (e.g., `send_message`, `create_task`) and optionally a `custom_fields` array.

#### Response Example
```json
{
  "conversation_id": "conv_12345",
  "actions": [
    {
      "type": "send_message",
      "message": "Order #ABC-12345 status: shipped\nTracking: XYZ789\nExpected delivery: 2024-03-15"
    },
    {
      "type": "create_task",
      "text": "Follow up on delivery",
      "complete_till": 1710460800
    }
  ],
  "custom_fields": [
    {
      "field_code": "ORDER_STATUS",
      "value": "shipped"
    }
  ]
}
```

#### Error Response (e.g., 500 or specific JSON response for errors)
Returns a JSON object indicating an error occurred during processing.

#### Error Response Example
```json
{
  "conversation_id": "conv_12345",
  "actions": [
    {
      "type": "send_message",
      "message": "Sorry, I could not find that order. Please check the order number and try again."
    }
  ]
}
```
```

--------------------------------

### Webhooks: Subscribe and Handle Events in Kommo

Source: https://context7.com/context7/developers_kommo_com-docs-kommo-for-developers/llms.txt

Provides code examples for subscribing to Kommo webhooks via the API to receive real-time notifications for entity changes. It also includes an Express.js handler for processing incoming webhook requests.

```javascript
// Subscribe to webhooks via API
async function subscribeToWebhooks() {
  const webhooks = [
    {
      destination: 'https://yourapp.com/webhooks/leads',
      settings: ['add_lead', 'update_lead', 'delete_lead', 'status_lead']
    },
    {
      destination: 'https://yourapp.com/webhooks/contacts',
      settings: ['add_contact', 'update_contact']
    }
  ];

  const response = await fetch(`https://${DOMAIN}/api/v4/webhooks`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(webhooks)
  });

  return await response.json();
}

```

```javascript
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/webhooks/leads', (req, res) => {
  const webhookData = req.body;

  console.log('Webhook received:', webhookData);
  console.log('Event type:', webhookData.leads?.status?.[0]?.type);

  // Process webhook
  if (webhookData.leads?.status?.[0]?.type === 'add') {
    const newLeads = webhookData.leads.status[0].add;
    newLeads.forEach(lead => {
      console.log(`New lead created: ${lead.name} (ID: ${lead.id})`);
      // Trigger custom business logic
      processNewLead(lead);
    });
  } else if (webhookData.leads?.status?.[0]?.type === 'update') {
    const updatedLeads = webhookData.leads.status[0].update;
    updatedLeads.forEach(lead => {
      console.log(`Lead updated: ${lead.id}`);
      syncLeadToExternalSystem(lead);
    });
  }

  // Always respond quickly to acknowledge receipt
  res.status(200).send('OK');
});

function processNewLead(lead) {
  // Custom business logic here
  console.log('Processing new lead:', lead);
}

function syncLeadToExternalSystem(lead) {
  // Sync to external CRM or database
  console.log('Syncing lead:', lead);
}

app.listen(3000, () => console.log('Webhook server running on port 3000'));

```

--------------------------------

### Initialize and Manage VoIP Calls with Kommo API (JavaScript)

Source: https://context7.com/context7/developers_kommo_com-docs-kommo-for-developers/llms.txt

This JavaScript code demonstrates how to initialize the Kommo VoIP widget, handle incoming and outgoing calls, and log call details. It uses Kommo's AMOCRM object for UI interactions and AJAX for VoIP service communication. Ensure you replace placeholder URLs and IDs with your actual VoIP service details.

```javascript
// Initialize VoIP widget
(function() {
  var VoIPWidget = {
    callbacks: {
      init: function() {
        // Register VoIP integration
        AMOCRM.addVoIPListener({
          name: 'YourTelephony',
          id: 'your_voip_id',
          events: {
            onCall: this.handleIncomingCall.bind(this),
            onCallComplete: this.handleCallComplete.bind(this)
          }
        });

        return true;
      },

      // Handle incoming call
      handleIncomingCall: function(callData) {
        var phoneNumber = callData.phone;

        // Create call notification in Kommo
        AMOCRM.notifications.show_call({
          header: 'Incoming Call',
          text: 'From: ' + phoneNumber,
          button_ok: 'Answer',
          button_cancel: 'Decline'
        }).then(function(result) {
          if (result === 'ok') {
            // Answer call via your VoIP service
            $.ajax({
              url: 'https://yourvoip.com/api/answer',
              method: 'POST',
              data: { call_id: callData.id },
              success: function() {
                // Start call timer
                AMOCRM.startCallTimer(callData.id);

                // Find or create contact with this phone
                VoIPWidget.findContact(phoneNumber, function(contact) {
                  // Open contact card
                  AMOCRM.openCard('contacts', contact.id);
                });
              }
            });
          } else {
            // Decline call
            $.ajax({
              url: 'https://yourvoip.com/api/decline',
              method: 'POST',
              data: { call_id: callData.id }
            });
          }
        });
      },

      // Make outbound call from Kommo
      bind_actions: function() {
        // Click-to-call on phone numbers
        $(document).on('click', '.phone-number', function(e) {
          var phone = $(this).text();
          VoIPWidget.makeCall(phone);
          e.preventDefault();
        });

        return true;
      },

      // Handle call completion
      handleCallComplete: function(callData) {
        // Stop timer
        AMOCRM.stopCallTimer(callData.id);

        // Create call note with recording
        var noteData = {
          note_type: 'call',
          entity_id: callData.entity_id,
          entity_type: callData.entity_type,
          parameters: {
            duration: callData.duration,
            phone: callData.phone,
            call_status: callData.status,
            link: callData.recording_url
          }
        };

        AMOCRM.post('/api/v4/leads/' + callData.entity_id + '/notes',
          noteData,
          function(response) {
            console.log('Call logged:', response);
          }
        );
      }
    },

    // Initiate outbound call
    makeCall: function(phoneNumber) {
      $.ajax({
        url: 'https://yourvoip.com/api/call',
        method: 'POST',
        data: { phone: phoneNumber },
        success: function(response) {
          AMOCRM.notifications.show_message({
            text: 'Calling ' + phoneNumber,
            header: 'Call Started'
          });

          AMOCRM.startCallTimer(response.call_id);
        }
      });
    },

    // Find contact by phone number
    findContact: function(phone, callback) {
      AMOCRM.get('/api/v4/contacts', {
        query: phone
      }, function(data) {
        if (data._embedded && data._embedded.contacts.length > 0) {
          callback(data._embedded.contacts[0]);
        } else {
          // Create new contact if not found
          AMOCRM.post('/api/v4/contacts', {
            name: 'New Contact',
            custom_fields_values: [{
              field_code: 'PHONE',
              values: [{ value: phone }]
            }]
          }, callback);
        }
      });
    }
  };

  return VoIPWidget;
}());
```

--------------------------------

### Private Integration: Fetch Leads using Long-Lived Token (JavaScript)

Source: https://context7.com/context7/developers_kommo_com-docs-kommo-for-developers/llms.txt

Demonstrates how to set up a private integration using a long-lived access token to retrieve lead data from the Kommo API. Requires a Kommo domain and a valid long-lived access token. Outputs lead details such as ID, name, and price.

```javascript
const KOMMO_DOMAIN = 'yoursubdomain.kommo.com';
const ACCESS_TOKEN = 'your_long_lived_token_here';

// Fetch all leads
fetch(`https://${KOMMO_DOMAIN}/api/v4/leads`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${ACCESS_TOKEN}`,
    'Content-Type': 'application/json'
  }
})
.then(response => {
  if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
  return response.json();
})
.then(data => {
  console.log('Leads retrieved:', data._embedded.leads);
  // Process leads data
  data._embedded.leads.forEach(lead => {
    console.log(`Lead #${lead.id}: ${lead.name} - ${lead.price}`);
  });
})
.catch(error => {
  console.error('Error fetching leads:', error);
});
```

--------------------------------

### Webhooks Configuration and Handling

Source: https://context7.com/context7/developers_kommo_com-docs-kommo-for-developers/llms.txt

Configure webhooks to receive real-time event notifications from Kommo when entities change, eliminating the need for polling.

```APIDOC
## POST /api/v4/webhooks

### Description
Subscribes your application to receive real-time notifications for specific Kommo events.

### Method
POST

### Endpoint
/api/v4/webhooks

### Parameters
#### Request Body
- **destination** (string) - Required - The URL where Kommo should send webhook notifications.
- **settings** (array) - Required - An array of event types to subscribe to.
  - Example event types: 'add_lead', 'update_lead', 'delete_lead', 'status_lead', 'add_contact', 'update_contact'.

### Request Example
```json
[
  {
    "destination": "https://yourapp.com/webhooks/leads",
    "settings": ["add_lead", "update_lead", "delete_lead", "status_lead"]
  },
  {
    "destination": "https://yourapp.com/webhooks/contacts",
    "settings": ["add_contact", "update_contact"]
  }
]
```

### Response
#### Success Response (200)
- **_embedded** (object) - Contains the created webhook subscriptions.
  - **webhooks** (array) - An array of created webhook subscription objects.
    - **id** (integer) - The ID of the webhook subscription.
    - **destination** (string) - The destination URL for the webhook.
    - **settings** (array) - The list of subscribed event types.
    - ... (other webhook properties)

#### Response Example
```json
{
  "_embedded": {
    "webhooks": [
      {
        "id": 1,
        "destination": "https://yourapp.com/webhooks/leads",
        "settings": ["add_lead", "update_lead", "delete_lead", "status_lead"],
        "created_at": 1678888000,
        "_links": {
          "self": {
            "href": "https://yoursubdomain.kommo.com/api/v4/webhooks/1"
          }
        }
      }
    ]
  }
}
```
```

--------------------------------

### CRM API: Create and Update Leads in Kommo

Source: https://context7.com/context7/developers_kommo_com-docs-kommo-for-developers/llms.txt

Demonstrates how to create a new lead with custom fields, linked contacts, and tags using the Kommo CRM API. It also shows how to update a lead's status and add a note.

```javascript
const DOMAIN = 'yoursubdomain.kommo.com';
const TOKEN = 'your_access_token';

// Create a new lead with custom fields and linked contacts
async function createLead() {
  const leadData = {
    name: 'New deal from website',
    price: 50000,
    status_id: 0,
    pipeline_id: 12345,
    responsible_user_id: 67890,
    custom_fields_values: [
      {
        field_id: 123,
        values: [{ value: 'Important client' }]
      }
    ],
    _embedded: {
      contacts: [
        {
          id: 11111,
          is_main: true
        }
      ]
    },
    tags: [
      { name: 'website' },
      { name: 'hot-lead' }
    ]
  };

  try {
    const response = await fetch(`https://${DOMAIN}/api/v4/leads`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify([leadData])
    });

    const result = await response.json();
    console.log('Lead created:', result._embedded.leads[0]);
    return result._embedded.leads[0].id;
  } catch (error) {
    console.error('Failed to create lead:', error);
    throw error;
  }
}

// Update lead status and add note
async function updateLeadStatus(leadId, statusId) {
  const updateData = {
    id: leadId,
    status_id: statusId,
    updated_at: Math.floor(Date.now() / 1000)
  };

  const response = await fetch(`https://${DOMAIN}/api/v4/leads/${leadId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(updateData)
  });

  // Add note to lead
  const noteData = {
    note_type: 'common',
    entity_id: leadId,
    parameters: {
      text: 'Status updated via API'
    }
  };

  await fetch(`https://${DOMAIN}/api/v4/leads/${leadId}/notes`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify([noteData])
  });

  return await response.json();
}

```

--------------------------------

### Register Custom Digital Pipeline Action (JavaScript)

Source: https://context7.com/context7/developers_kommo_com-docs-kommo-for-developers/llms.txt

This snippet demonstrates how to register a custom action within Kommo's Digital Pipeline Automation builder using JavaScript. It defines the action's settings, icon, and handler function. The handler function fetches lead data, prepares invoice information, sends it to an external accounting system via AJAX, and updates Kommo with the invoice details or logs any errors.

```javascript
// Register custom Digital Pipeline action
(function() {
  var AutomationWidget = {
    callbacks: {
      init: function() {
        // Register custom action in Digital Pipeline
        if (typeof AMOCRM.addDigitalPipelineAction !== 'undefined') {
          AMOCRM.addDigitalPipelineAction({
            id: 'send_to_accounting',
            name: 'Send to Accounting System',
            icon: 'icon-money',
            settings: [
              {
                type: 'select',
                name: 'department',
                label: 'Department',
                options: [
                  { value: 'sales', label: 'Sales' },
                  { value: 'support', label: 'Support' }
                ]
              },
              {
                type: 'text',
                name: 'invoice_number',
                label: 'Invoice Number Template'
              }
            ],
            handler: this.sendToAccounting.bind(this)
          });
        }

        return true;
      },

      // Action handler
      sendToAccounting: function(params) {
        var leadId = params.entity.id;
        var settings = params.settings;

        // Get full lead data
        AMOCRM.get('/api/v4/leads/' + leadId, {
          with: 'contacts,companies'
        }, function(lead) {
          // Prepare invoice data
          var invoiceData = {
            lead_id: lead.id,
            amount: lead.price,
            department: settings.department,
            invoice_number: settings.invoice_number.replace('{id}', lead.id),
            customer: lead._embedded.contacts[0].name,
            created_at: new Date().toISOString()
          };

          // Send to external accounting system
          $.ajax({
            url: 'https://your-accounting.com/api/invoices',
            method: 'POST',
            headers: {
              'Authorization': 'Bearer YOUR_ACCOUNTING_TOKEN'
            },
            data: JSON.stringify(invoiceData),
            contentType: 'application/json',
            success: function(response) {
              console.log('Invoice created:', response);

              // Add note to lead
              AMOCRM.post('/api/v4/leads/' + leadId + '/notes', {
                note_type: 'common',
                entity_id: leadId,
                parameters: {
                  text: 'Invoice #' + response.invoice_id + ' sent to accounting'
                }
              });

              // Update custom field with invoice number
              AMOCRM.patch('/api/v4/leads/' + leadId, {
                custom_fields_values: [{
                  field_code: 'INVOICE_NUMBER',
                  values: [{ value: response.invoice_id }]
                }]
              });
            },
            error: function(error) {
              console.error('Failed to create invoice:', error);

              // Log error in lead
              AMOCRM.post('/api/v4/leads/' + leadId + '/notes', {
                note_type: 'common',
                entity_id: leadId,
                parameters: {
                  text: 'ERROR: Failed to send to accounting - ' + error.message
                }
              });
            }
          });
        });
      }
    }
  };

  return AutomationWidget;
}());
```

--------------------------------

### OAuth2 Public Integration Authentication

Source: https://context7.com/context7/developers_kommo_com-docs-kommo-for-developers/llms.txt

Details the OAuth2 authorization flow for public integrations, including obtaining authorization codes, exchanging them for tokens, and refreshing access tokens.

```APIDOC
## OAuth2 Authentication Flow

### Description
This section outlines the steps for authenticating public integrations using OAuth2, allowing access to user data across multiple Kommo accounts.

### Method
Various (GET, POST)

### Endpoint
- Authorization URL: `https://www.kommo.com/oauth`
- Token Endpoint: `https://www.kommo.com/oauth2/access_token`

### Parameters
#### Authorization Request (Step 1)
- **client_id** (string) - Required - Your application's client ID.
- **redirect_uri** (string) - Required - The URL to redirect the user back to after authorization.
- **response_type** (string) - Required - Must be `code` for authorization code grant.
- **state** (string) - Optional - A unique string to protect against CSRF attacks.

#### Token Exchange Request (Step 2)
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required - Your application's client secret.
- **grant_type** (string) - Required - Must be `authorization_code` for the initial token exchange.
- **code** (string) - Required - The authorization code received from the callback.
- **redirect_uri** (string) - Required - The same redirect URI used in the authorization request.

#### Token Refresh Request (Step 3)
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required - Your application's client secret.
- **grant_type** (string) - Required - Must be `refresh_token`.
- **refresh_token** (string) - Required - The refresh token obtained during the initial token exchange.
- **redirect_uri** (string) - Required - The same redirect URI used in the authorization request.

### Request Example (Step 1: Redirect User)
```javascript
const CLIENT_ID = 'your_client_id';
const REDIRECT_URI = 'https://yourapp.com/oauth/callback';
const STATE = 'random_secure_state_string';

const authUrl = `https://www.kommo.com/oauth?client_id=${CLIENT_ID}&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&response_type=code&state=${STATE}`;
// Redirect user to authUrl
```

### Request Example (Step 2: Handle Callback & Exchange Code)
```javascript
const express = require('express');
const app = express();

app.get('/oauth/callback', async (req, res) => {
  const { code, state, referer } = req.query;

  if (state !== STATE) {
    return res.status(400).send('Invalid state parameter');
  }

  try {
    const tokenResponse = await fetch('https://www.kommo.com/oauth2/access_token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        client_id: CLIENT_ID,
        client_secret: 'your_client_secret',
        grant_type: 'authorization_code',
        code: code,
        redirect_uri: REDIRECT_URI
      })
    });

    const tokens = await tokenResponse.json();
    // Store tokens securely
    console.log('Access token:', tokens.access_token);
    console.log('Refresh token:', tokens.refresh_token);
    console.log('Account domain:', tokens.base_domain);

    res.send('Authorization successful!');
  } catch (error) {
    console.error('OAuth error:', error);
    res.status(500).send('Authorization failed');
  }
});
```

### Response
#### Success Response (200)
- **access_token** (string) - The access token for making API requests.
- **refresh_token** (string) - The token used to obtain a new access token.
- **expires_in** (integer) - The lifetime in seconds of the access token.
- **base_domain** (string) - The domain of the Kommo account.

#### Response Example (Token Exchange)
```json
{
  "access_token": "generated_access_token",
  "refresh_token": "generated_refresh_token",
  "expires_in": 86400,
  "token_type": "Bearer",
  "account_id": 123456,
  "base_domain": "yoursubdomain.kommo.com"
}
```

#### Error Response (e.g., 400)
```json
{
  "errors": [
    {
      "code": "invalid_request",
      "description": "Missing required parameter: client_id"
    }
  ]
}
```
```

--------------------------------

### Kommo Chats API: JavaScript Messaging Integration

Source: https://context7.com/context7/developers_kommo_com-docs-kommo-for-developers/llms.txt

This JavaScript code demonstrates how to use the Kommo Chats API to integrate custom messaging channels. It includes functions to create a chat scope, send messages within a conversation, and handle incoming messages from customers. Ensure you have your API domain and token set.

```javascript
// Connect a new chat channel (scope)
async function createChatScope() {
  const scopeData = {
    name: 'WhatsApp Business',
    avatar: 'https://yourcdn.com/whatsapp-icon.png',
    code: 'whatsapp_business'
  };

  const response = await fetch(`https://${DOMAIN}/api/v4/customers/chats/scopes`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(scopeData)
  });

  const result = await response.json();
  console.log('Scope created:', result);
  return result.scope_id;
}

// Create or update conversation
async function sendMessage(phoneNumber, messageText, scopeId) {
  // First, find or create conversation
  const conversationData = {
    source: {
      external_id: phoneNumber,
      type: 'phone'
    },
    scope_id: scopeId
  };

  const convResponse = await fetch(`https://${DOMAIN}/api/v4/customers/chats/conversations`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(conversationData)
  });

  const conversation = await convResponse.json();
  const conversationId = conversation.id;

  // Send message to conversation
  const messageData = {
    conversation_id: conversationId,
    message: {
      type: 'text',
      text: messageText
    },
    author: {
      type: 'integration',
      name: 'WhatsApp Bot'
    }
  };

  const msgResponse = await fetch(`https://${DOMAIN}/api/v4/customers/chats/messages`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(messageData)
  });

  return await msgResponse.json();
}

// Receive incoming message from external system
async function handleIncomingMessage(fromPhone, messageText, scopeId) {
  const messageData = {
    conversation: {
      source: {
        external_id: fromPhone,
        type: 'phone'
      },
      scope_id: scopeId
    },
    message: {
      type: 'text',
      text: messageText,
      timestamp: Math.floor(Date.now() / 1000)
    },
    author: {
      type: 'customer',
      external_id: fromPhone,
      name: 'Customer'
    }
  };

  const response = await fetch(`https://${DOMAIN}/api/v4/customers/chats/messages`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(messageData)
  });

  return await response.json();
}

```

--------------------------------

### SalesBot Custom Action and Express.js Handler (JavaScript)

Source: https://context7.com/context7/developers_kommo_com-docs-kommo-for-developers/llms.txt

Defines a custom action configuration for SalesBot, including its name, description, ID, handler URL, and required parameters. It also includes an Express.js route handler that receives order ID, queries an external order system, and formats a response for SalesBot, optionally creating a follow-up task. Error handling is included for failed order lookups. This snippet is designed to be integrated into a Node.js backend.

```javascript
// SalesBot custom action implementation
{
  "name": "Check Order Status",
  "description": "Checks order status in external system",
  "action_id": "check_order_status",
  "handler_url": "https://yourapp.com/salesbot/check-order",
  "parameters": [
    {
      "name": "order_id",
      "type": "text",
      "required": true,
      "description": "Order number to check"
    }
  ]
}

// Express.js handler for SalesBot action
app.post('/salesbot/check-order', async (req, res) => {
  const { conversation_id, contact_id, order_id } = req.body;

  try {
    // Query external order system
    const orderResponse = await fetch(`https://orders.example.com/api/orders/${order_id}`, {
      headers: { 'Authorization': 'Bearer ORDER_API_TOKEN' }
    });

    const order = await orderResponse.json();

    // Prepare response for SalesBot
    const botResponse = {
      conversation_id: conversation_id,
      actions: [
        {
          type: 'send_message',
          message: `Order #${order_id} status: ${order.status}\nTracking: ${order.tracking_number}\nExpected delivery: ${order.estimated_delivery}`
        }
      ],
      custom_fields: [
        {
          field_code: 'ORDER_STATUS',
          value: order.status
        }
      ]
    };

    // If order is shipped, set reminder
    if (order.status === 'shipped') {
      botResponse.actions.push({
        type: 'create_task',
        text: 'Follow up on delivery',
        complete_till: Math.floor(new Date(order.estimated_delivery).getTime() / 1000)
      });
    }

    res.json(botResponse);
  } catch (error) {
    console.error('Order check failed:', error);

    // Return error message to user
    res.json({
      conversation_id: conversation_id,
      actions: [
        {
          type: 'send_message',
          message: 'Sorry, I could not find that order. Please check the order number and try again.'
        }
      ]
    });
  }
});

// SalesBot scenario definition (via UI or API)
const salesbotScenario = {
  name: "Order Support Bot",
  trigger: {
    type: "message_contains",
    keywords: ["order", "delivery", "tracking"]
  },
  steps: [
    {
      type: "message",
      text: "I can help you check your order status. Please provide your order number."
    },
    {
      type: "wait_for_input",
      variable: "order_id"
    },
    {
      type: "custom_action",
      action_id: "check_order_status",
      parameters: {
        order_id: "{{order_id}}"
      }
    }
  ]
};

```

--------------------------------

### SalesBot Custom Action Definition

Source: https://context7.com/context7/developers_kommo_com-docs-kommo-for-developers/llms.txt

Defines the structure and parameters for a custom SalesBot action, including its name, handler URL, and required inputs.

```APIDOC
## SalesBot Custom Action Definition

### Description
Defines a custom action that can be triggered within a Kommo SalesBot conversation flow. This includes specifying the action's identifier, the endpoint that will handle its logic, and any parameters it requires from the user or the conversation context.

### Method
Not Applicable (Configuration Object)

### Endpoint
Not Applicable

### Parameters
#### Request Body
- **name** (string) - Required - The user-facing name of the custom action.
- **description** (string) - Optional - A brief explanation of what the action does.
- **action_id** (string) - Required - A unique identifier for this custom action.
- **handler_url** (string) - Required - The URL of the endpoint that will process this action's logic.
- **parameters** (array) - Optional - An array of objects defining the input parameters required by the action.
  - **name** (string) - Required - The name of the parameter.
  - **type** (string) - Required - The data type of the parameter (e.g., 'text', 'number', 'boolean').
  - **required** (boolean) - Required - Indicates if this parameter is mandatory.
  - **description** (string) - Optional - A description of the parameter.

### Request Example
```json
{
  "name": "Check Order Status",
  "description": "Checks order status in external system",
  "action_id": "check_order_status",
  "handler_url": "https://yourapp.com/salesbot/check-order",
  "parameters": [
    {
      "name": "order_id",
      "type": "text",
      "required": true,
      "description": "Order number to check"
    }
  ]
}
```

### Response
#### Success Response (200)
No direct response to this definition, but successful definition allows the action to be used in a scenario.

#### Response Example
N/A
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.