Getting Started with Salesbot

To get started, you need to connect the integration with chats in the left column of the Digital Pipeline. You will find instructions for each messenger in the settings window. After connecting the chat integration, you can activate the Salesbot to handle incoming new chats, as well as configure bots for specific stages.

Configure Salesbot

You can connect the Salesbot in two ways:

Go to the Leads section ➡️ Automate ➡️ select a stage ➡️ Add Trigger ➡️ choose Salesbot.

Next, select Create a new bot. When the modal window opens, you can choose a standard template or create a new bot.

Go to the Settings section ➡️ Communication tools tab ➡️ Salesbots ➡️ Create a new bot or import.

When opening the modal window with Salesbot steps, you can click View Source to view the bot's code.

Leads that entered the stage before the action appeared in the Digital Pipeline will be ignored unless you tick Apply the trigger to all leads already in this stage.

Salesbot language

Salesbot uses a structured JSON object with specific keys. The example below will ask the question, "Please provide your phone number and email," and set the "salesbot" tag. After the user responds, it will validate the data and reply with one of the specified messages. For more details about presets, please refer to the next section.

[
    {
        "question": [
            {
                "handler": "show",
                "params": {
                    "type": "text",
                    "value": "Please provide your phone number and email"
                }
            },
            {
                "handler": "action",
                "params": {
                    "name": "set_tag",
                    "params": {
                        "type": 2,
                        "value": "salesbot"
                    }
                }
            }
        ],
        "answer": [
            {
                "handler": "preset",
                "params": {
                    "name": "contacts.validate_base_info",
                    "params": {
                        "empty_email": "Please provide your e-mail",
                        "empty_phone": "Please provide your phone number",
                        "invalid_phone": "It appears that the phone number may be incorrect",
                        "success": "Thank you",
                        "empty_all": "Please provide your phone number and email"
                    }
                }
            }
        ]
    }
]

The object must contain the keys "question", "answer", or "finish".

The data in the "question" object handle the actions that will occur when a message is sent to the user.
The data in the "answer" object manage the actions that will take place when the user responds.
The data in the "finish" object define the actions that will occur when the bot is completed.

📘
There can be multiple keys. However, there is a limitation on the size of the JSON, which cannot exceed 64KB.

In the "question", "answer", and "finish" objects, there should be handlers.

Before adding the JSON object to the bot, make sure to validate it.

Salesbot Error Handler

If a message from the bot cannot be delivered to the client, for example, when the client has blocked messages from that chat, the bot can handle the error and execute specific handlers.

Example:

{
     "0":{
        "question":[
           ...
        ],
        "answer":[
           ...
        ]
     },
     "error":[
        {
           "handler":"action",
           "params":{
              "name":"change_status",
              "params":{
                 "value":142
              }
           }
        }
     ]
  }

Salesbot Handlers

Code	Description
show	Sends a message with text
buttons	Processing response received from buttons from instant messengers
action	Action
meta	Meta data processing
condition	Condition
validations	Validation
preset	Processes data for a specific algorithm
goto	Transition of the script to a certain step
wait_answer	Waits for the answer
find	Search
filter	Filtration
send_internal	Sends an internal message
stop	Stops the bot

show

🚧
This handler accepts incoming leads if it is configured in Salesbot.

The "show" handler sends a message or buttons to the client's chat. Any text sent currently supports the following placeholders:

Placeholder	Description
{{contact.name}}, {{name}}	Contact name
{{lead.id}}	Lead ID
{{contact.id}}	Contact ID
{{origin}}	Source of the lead (Telegram,Viber, Facebook)
{{lead.source_id}}	Lead source ID
{{message_text}}	Received message from the client in the logical block of the response
{{lead.cf.#custom_field_id#}}, {{contact.cf.#custom_field_id#}}, {{company.cf.#custom_field_id#}}	The value of the custom field of a lead/contact/company. Replace #custom_field_id# with the ID of the additional field.
{{rand}}	Random string
{{short_rand}}	Short random string
{{short_rand_num}}	Random number from 1111 to 9999
{{message_text.email}}	Email (if it is present in the client's message)
{{message_text.phone}}	Phone number (if it is present in the client's message)
{{regexp./([1-9]+) things /}}	The value by regular expression from the user's response. The value from the parentheses will be substituted. It can be used in the answer block.
{{lead.price}}	Lead sale value
{{current_date}}	Current date
{{lead.status_id}}	Lead stage ID
{{cf.talk.nps}}	Conversation evaluation
{{lead.responsible.id}}, {{contact.responsible.id}}, {{company.responsible.id}}	Lead/contact/company responsible user ID
{{lead.responsible.name}}, {{contact.responsible.name}}, {{company.responsible.name}}	Lead/contact/company responsible user name
{{lead.responsible.email}}, {{contact.responsible.email}}, {{company.responsible.email}}	Lead/contact/company responsible user email

For contact placeholders, either the primary contact of the lead or the contact from the chat in which communication with the client is taking place is used.

text

Parameters of the handler for sending text.

{
  "handler": "show",
  "params": {
    "type": "text",
    "value": "Please provide your phone number and e-mail",
    "quick_replies": [
      "user_phone_number",
      "user_email"
    ]
  }
}

Parameter	Data type	Description
type	string	It should be `"text"`
value	string	Text to be sent to the user
quick_replies	array	An array of elements (currently available: "user_phone_number" and "user_email") sends quick reply buttons. This feature is available only for Facebook and displays buttons containing the user's Facebook account information (phone number, email).

buttons

Parameters of the handler for sending buttons.

{
  "handler": "show",
  "params": {
    "type": "buttons",
    "value": "Please choose the type of participation:",
    "buttons": [
      "Personal presence",
      "Online"
    ]
  }
}

Parameter	Data type	Description
type	string	It should be `"buttons"`
value	string	Text to be sent to the user (In Messenger, texts longer than 80 characters will be truncated)
buttons	array	An array whose elements are the text of the buttons that will be sent
accept_unsorted	bool	Set to false if you do not need to parse the incoming leads at the first response

buttons_url

Parameters of the handler for sending buttons with links to external resources.

{
    "handler": "show",
    "params": {
        "type": "buttons_url",
        "value": "Links to external resources",
        "buttons": [
            {
                "text": "Bing",
                "url": "https://www.bing.com"
            },
            {
                "text": "Google",
                "url": "https://google.com"
            }
        ]
    }
}

Parameter	Data type	Description
type	string	It should be `"buttons_url"`. It sends buttons with links.
value	string	Text to be sent to the user (In Messenger, text longer than 80 characters will be truncated)
buttons	array	An array whose elements are the text of the buttons that will be sent

If you want to send links to social media and enable auto-linking, the links should be in the following format:

Social media	Link	Comments
Facebook Messenger	https://m.me/123/?ref=VisitorUid_{{visitor_uid}}	Where '123' is the group ID
WhatsApp	https://wa.me/7895?text=ID:%20{{session_id}}	where '7895' is the WhatsApp phone number linked to the account.
Viber	viber://pa?chatURI=bot&context=VisitorUid_{{visitor_uid}}	where 'bot' is the name of the public account
Telegram	tg://resolve?domain=bot&start=VisitorUid_{{visitor_uid}}	where 'bot' is the name of the bot

buttons

The buttons handler is designed to be inserted into the response logic block and allows for processing responses from the sent buttons or exact match responses.

{
  "handler": "buttons",
  "params": [
    {
      "value": "Personal presence",
      "params": [
        {
          "handler": "...",
          "params": {...}
        }
      ]
    },
    {
      "value": "Online",
      "params": [
        {
          "handler": "...",
          "params": {...}
        }
      ]
    }
  ]
}

The "buttons" handler expects an array of objects to enter into parameters, in which any of the handlers specified on this page can be called.

goto

The goto handler allows you to jump to a specific step in the scenario, for example, if you need to repeatedly perform certain actions.

📘
The step count starts from 0.

{
    "handler": "goto",
    "params": {
        "type": "question",
        "step": 3
    }
}

Parameter	Data type	Description
type	string	The block to which the jump will be made to. Possible values are `"question"`, `"answer"`, and `"finish"`.
step	int	The step of the bot the jump will be made to.

wait_answer

It is used to wait for a response from the user to a given question. It allows you to ask the user a question and wait for their answer before proceeding with further actions.

{
  "handler": "wait_answer",
  "params": {
    "type": "question",
    "step": 2
  }
}

Parameter	Data type	Description
type	string	The block to which the jump will be made to. Possible values are `"question"` and `"answer"`.
step	int	The step of the bot the jump will be made to.

find

The "find" handler allows you to locate an entity and use its data. If an element is found, you can use the following placeholders:

{{founded_id}} – if a list item is found.
{{contact_double.*}} – if a contact duplicate is found, allowing you to access its fields similarly to the {{contact.*}} placeholders.

{
  "handler": "find",
  "params": {
    "type": "contact_double",
    "params":{
      "type": "name",
      "actions": [
        {
          "handler": "show",
          "params": {
            "type": "buttons",
            "value": "Is it your number {{contact_double.cf.3574}}?",
            "buttons": [
              "Yes",
              "No"
            ]
          }
        }
      ]
    }
  }
}

Parameter	Data type	Description
type	string	`contact_double` – search for a duplicate of the current contact `catalog_elements` – search for a list element
params[type]	string	`type` – can be `"name"` (search is available by name)
params[actions]	array	Actions to be performed if an entity was found
value	string	The word that is looking for, placeholders from the `"show"` block can be used
catalog_id	int	ID of the list where you are looking for an element

filter

The "filter" handler allows you to find an entity and use its data. If an element is found, you can use the placeholders for the custom fields of external_lead and external_contact.

{
   "handler": "filter",
   "params": {
     "type": 2,
     "value": "{{lead.cf.111}}",
     "custom_fields_id": 222,
     "actions": [
       {
         "handler": "action",
         "params": {
           "name": "set_custom_fields",
           "params": {
             "type": 1,
             "value": "{{external_contact.cf.333}}",
             "custom_fields_id": 444,
             "enum": "WORK"
           }
         }
       }
     ]
   }
 }

Parameter	Date type	Description
type	int	The type of entity for which the filtering occurs: 1 – contact, 2 – lead
value	string	The word by which we filter can include placeholders from the `"show"` block
custom_fields_id	int	The ID of the custom field by which the filter will be applied

action

The "action" handler allows you to perform one of the possible actions:

Action	Description
unsorted	Actions with Incoming Leads
change_status	Change of a stage
set_tag	Setting the tag
unset_tag	Deleting a tag
set_custom_fields	Setting lead/contact field values
subscribe	User subscription to the chat in the entity
unsubscribe	User unsubscription from the chat in the entity
add_lead_contact	Adding a lead and a contact that are linked to each other
set_budget	Setting the lead budget (sale)
add_linked_company	Add company
add_note	Add a note
link	Linking elements
change_responsible_user	Changing the responsible person
link_to_unsorted	Creating a contact from the incoming lead and associates it with the lead.

unsorted

The "unsorted" action allows you to accept or reject an Incoming Lead.

{
  "handler": "action",
  "params": {
    "name": "unsorted",
    "params": {
      "value": "accept"
    }
  }
},
{
  "handler": "action",
  "params": {
    "name": "unsorted",
    "params": {
      "value": "decline"
    }
  }
}

Parameter	Data type	Description
value	string	`"accept"` / `"decline"` for acceptance / decline of the incoming lead

change_status

The action "change_status" allows you to change the stage of the lead.

{
  "handler": "action",
  "params": {
    "name": "change_status",
    "params": {
      "value": 142
    }
  }
}

Parameter	Data type	Description
value	int	ID of the stage to which the lead will be transferred
entity	int or string	An optional parameter that can be `"double"`. If the `"find"` handler was used beforehand, the stage will be updated for the lead of the found contact, if it exists.

set_tag

The "set_tag" action will assign a tag to the lead or contact and supports the {{origin}} placeholder, which will specify the source of the lead.

{
  "handler": "action",
  "params": {
    "name": "set_tag",
    "params": {
      "type": 2,
      "value": "Salesbot"
    }
  }
},
{
  "handler": "action",
  "params": {
    "name": "set_tag",
    "params": {
      "type": 2,
      "value": "{{origin}}"
    }
  }
}

Parameter	Data type	Description
type	int	The type of entity to be tagged (1-contact, 2-lead)
value	string	Name of a tag

unset_tag

The "unset_tag" action removes the tag from a trade or contact

{
  "handler": "action",
  "params": {
    "name": "unset_tag",
    "params": {
      "type": 2,
      "value": "Salesbot"
    }
  }
}

Parameter	Data type	Description
type	int	The type of entity where tag will be deleted (1-contact, 2-leads)
value	string	Name of a tag to be deleted

set_custom_fields

The "set_custom_fields" action will set custom field values for a lead or contact. You can find the field IDs in the Setup section of a lead/contact or by using the method to get the list of entity fields. You can use placeholders described in the "show" section as values for the fields.

{
  "handler": "action",
  "params": {
    "name": "set_custom_fields",
    "params": {
      "type": 2,
      "value": "Value of the field",
      "custom_fields_id": 123,
      "option": "add"
    }
  }
},
{
  "handler": "action",
  "params": {
    "name": "set_custom_fields",
    "params": {
      "type": 2,
      "value": "{{message_text}}",
      "custom_fields_id": 987
    }
  }
},
{
  "handler": "action",
  "params": {
    "name": "set_custom_fields",
    "params": {
      "type": "lead",
      "value": "{{last_validation_result}}",
      "custom_field": "{{cf.talk.nps}}"
    }
  }
}

Parameter	Data type	Description
type	int	The entity type for which custom fields will be set (1-contact, 2-lead)
value	string	The value of the field that will be set can use placeholders from the `"show"` block. After the `"validations"` handler, it is permissible to use the placeholder `{{last_validation_result}}`, which will use the recognized data from the last `true` condition. For example, if the condition `"contains email"` was used, the found email will be substituted as the value.
custom_fields_id	int	The ID of the field in which the value will be set.
custom_field	string	The identifier of the field being modified can include the following: {{lead.price}} – the lead sale {{lead.name}} – the lead name {{contact.name}} – the contact name {{cf.talk.nps}} – the rating of the current conversation
calculated	bool	If it is necessary to try to calculate the value of this custom field using the formula, for example `{{lead.cf.123}} * {{lead.cf.456}}`
option	string	Use `“add”` option to add a value to a field of your choice. Available field types: phone number, email, multiselect list

The "subscribe" action will subscribe a user/group of users to chat.

{
  "handler": "action",
  "params": {
    "name": "subscribe",
    "params": {
      "type": "group",
      "value": 111
    }
  }
},
{
  "handler": "action",
  "params": {
    "name": "subscribe",
    "params": {
      "type": "user",
      "value": "{{lead.responsible_user_id}}"
    }
  }
}

Parameter	Data type	Description
type	string	`"group"` or `"user"`
value	int	The ID of the user group or the user ID.

unsubscribe

The "unsubscribe" action will unsubscribe a user/group of users to chat.

{
  "handler": "action",
  "params": {
    "name": "unsubscribe",
    "params": {
      "type": "user",
      "value": "{{lead.responsible_user_id}}"
    }
  }
}

Parameter	Data type	Description
type	string	`"group"` ,`"user"` or `"all"`
value	int	The ID of the user group or the user ID. Optional if you passed `"all"` as `"type"`.

add_lead_contact

The "add_lead_contact" action will create a lead and a contact and link them together. All fields for the lead and contact can be configured. The custom field values support the same placeholders as in the "show" handler . A "preset" is also supported, allowing the contact and lead to be created only if a message or phone number is received from the client.

{
  "handler": "action",
  "params": {
      "name": "add_lead_contact",
      "params": {
          "preset": "contacts.require_email_or_phone",
          "lead": {
              "name": "Lead name",
              "status_id": 142,
              "responsible_user_id": 123,
              "price": 2000,
              "tags": "",
              "custom_fields": [
                  {
                      "id": 77744111,
                      "values": [
                          {
                              "value": "{{contact.name}}"
                          }
                      ]
                  },
                  {
                      "id": 77744222,
                      "values": [
                          {
                              "value": "{{lead.cf.77744222}}"
                          }
                      ]
                  }
              ]
          },
          "contact": {
              "name": "Contact name",
              "responsible_user_id": 123,
              "tags": "",
              "custom_fields": [
                  {
                      "id": 77744444,
                      "values": [
                          {
                              "value": "{{message_text.email}}",
                              "enum": "WORK"
                          }
                      ]
                  },
                  {
                      "id": 77744555,
                      "values": [
                          {
                              "value": "{{message_text.phone}}",
                              "enum": "WORK"
                          }
                      ]
                  }
              ]
          }
      }
  }
}

Parameter	Data type	Description
lead	object	Set of lead fields
contact	object	Set of contact fields
preset	string	Optional parameter. One preset `contacts.require_email_or_phone` is supported, which checks whether the phone or email is sent in a message from the client

set_budget

The "set_budget" action will set the sale for the lead.

{
  "handler": "action",
  "params": {
    "name": "set_budget",
    "params": {
      "value": "{{lead.cf.555123}}*{{lead.cf.555321}}"
    }
  }
}

Parameter	Data type	Description
value	string	The number that will be recorded in the lead sale. This field can also be computed, allowing any placeholders from the `"show"` block to be used in the expression. Available operations include +, -, _, and /. You can also use parentheses, for example: `({{lead.cf.555123}} + 1){{lead.cf.555321}}`.

add_linked_company

"add_linked_company" action adds a company linked to a lead and a contact.

{
  "handler": "action",
  "params": {
    "name": "add_linked_company",
    "params": {
      "name": "{{message_text}}"
    }
  }
}

Parameter	Data type	Description
name	string	Company name, placeholders can be used from the `"show"` block

add_note

add_note action adds a note.

{
  "handler": "action",
  "params": {
    "name": "add_note",
    "params": {
      "element_type": 1,
      "note_type": 4,
      "text": "Note text"
    }
  }
}

Parameter	Data type	Description
element_type	int	The entity to which the note will be attached: 1 – contact, 2 – lead
note_type	int	Type of note: 4 – regular note 10 – Incoming call note 11 – Outgoing call note 102 – Incoming text message note 103 – Outgoing SMS message note 25 – Service note
text	string	Note text, placeholders from the `"show"` block can be used in it

link

The "link" action links elements.

{
  "handler": "action",
  "params": {
    "name": "link",
    "params": {
      "from": 2,
      "to": 11,
      "to_id": "{{founded_id}}",
      "to_catalog_id": 123
    }
  }
}

Parameter	Data type	Description
from	int	The entity that the second entity will be linked to ( 1 – contact, 2 – lead)
from_id	int	An optional parameter. The ID of the entity that the second entity will be linked to. If not specified, the ID of the current entity will be used. Placeholders from the `"show"` section can also be used.
to	int	The entity to be linked: 1 – contact, 2 – lead, 3 – company, 11 – list element.
to_id	string	Id of the element to be linked, you can use the placeholders from the `"show"` section
to_catalog_id	int	An optional parameter, list ID (if the list element is linked)
quantity	int	An optional parameter, the number of list elements to be attached to the entity. Placeholders from the `"show"` section can be used.

change_responsible_user

The action change_responsible_user changes the responsible user for a lead or the associated contact.

{
  "handler": "action",
  "params": {
    "name": "change_responsible_user",
    "params": {
      "value": 123,
      "type": 2
    }
  }
}

Parameter	Data type	Description
value	int	ID of the user you want to make responsible
type	int	An optional parameter, the type of entity for which the responsible user is being changed: 1 – contact, 2 – lead. If not provided, the default is 2.

link_to_unsorted

The "link_to_unsorted" action links a chat from incoming leads to the specified contact in a lead. If the specified contact does not exist in the lead, the linking will not occur. If contact_id is not provided, a contact will be created in the specified lead.

{
  "handler": "action",
  "params": {
    "name": "link_to_unsorted",
    "params": {
      "entity_type": 2,
      "entity_id": "12345"
    }
  }
}

Parameter	Data type	Description
entity_type	int	Entity type ( 2 -lead)
entity_id	string	The ID of the entity to which the contact should be linked. Placeholders can be used, e.g. if a `"filter"` handler was used, you can use `{{external_lead.id}}`.
contact_id	string	An optional parameter. The ID of the contact to which the chat should be linked. The contact must be in the specified lead. Placeholders can be used, e.g. if a `"filter"` handler was used, you can use `{{external_contact.id}}`.

Parameter	Data type	Description
delimiter	string	The character that will separate the incoming content into elements.
values	array	An array of values where the elements of the incoming information will be stored. The values can be recorded in tags or lead fields.

condition

The "condition" handler is designed to create logical conditions.

{
  "handler": "condition",
  "params": {
    "term1": "chat.origin",
    "term2": "telegram",
    "operation": "=",
    "result": [
      {
        "handler": "action",
        "params": {
          "name": "change_status",
          "params": {
            "value": 123
          }
        }
      }
    ]
  }
}

Parameter	Data type	Description
term1	string	Condition 1 can be: `lead.tags` – which returns a list of tags, `chat.origin` – which returns the source which the request came from (Facebook, Telegram, Viber), any placeholder from the block described in the `"show"` handler section, for example `{{contact.name}}`
term2	string/obj	Condition 2: for the `in_range` operator, you need to pass an object with parameters; otherwise, a string or placeholder from the `"show"` handler section should be provided.
term2.from	int	The "from" value of the range.
term2.to	int	The "to" value of the range.
operation	string	The comparison operator: `"="`, `"! ="`, `"in"`, `"not_in"`, or `"in_range"`
result	array	If the comparison is successful, the array of handlers

Operators

Operator	Description
`"="`	The "=" operator checks if `"term1"` is equal to `"term2"`
`"!="`	The "!=" operator checks if `"term1"` is not equal to `"term2"`
`"in"`	It takes strings from `"term1"` and `"term2"`, splits them into values by commas, and searches for occurrences of values from `"term2"` in `"term1"`. If there is at least one match, the result handlers will be executed.
`"not_in"`	It takes strings from `"term1"` and `"term2"`, splits them into values by commas, and searches for occurrences of values from `"term2"` in `"term1"`. If there are no matches, the result handlers will be executed.
`"in_range"`	It finds all integers in `"term1"`. If at least one of these numbers falls within the range specified by `"term2"`, the array of result handlers will be executed.

validations

The "validations" handler is designed to create logical conditions.

{
  "handler": "validations",
  "params": {
    "logic": "and",
    "conditions": [
      {
        "client_value": "{{message_text}}",
        "type": "regex",
        "condition_value": "/[0-9]+/",
        "operation": "contains"
      },
      {
        "client_value": "{{message_text}}",
        "type": "simple",
        "condition_value": "654",
        "operation": "equal"
      },
      {
        "client_value": "{{message_text}}",
        "type": "range_numbers",
        "condition_value": {
          "from": 123,
          "to": 321
        },
        "operation": "contains"
      },
      {
        "client_value": "{{message_text}}",
        "type": "email",
        "condition_value": "",
        "operation": "contains"
      }
    ],
    "result": [
      {
        "handler": "goto",
        "params": {
          "type": "question",
          "step": 3
        }
      }
    ]
  }
}

Parameters	Data type	Description
logic	string	The logic for checking conditions is as follows: if `"and"` is specified, all conditions must be true; if `"or"` is specified, at least one of the conditions must be true.
conditions	array	The list of conditions for checking is described below
result	array	Upon successful validation, the array of handlers will be executed.

simple condition

A "simple" condition checks for equality/inequality or compares length

{
  "client_value": "{{message_text}}",
  "type": "simple",
  "condition_value": "654",
  "operation": "equal"
}

Parameter	Data type	Description
client_value	string	The value being checked can be a placeholder from `"show"` handler section, for example, `"{{contact.name}}"`.
type	string	It should be set to `"simple"`
condition_value	string	It can be a a placeholder from `"show"` handler section (e.g. `"{{contact.name}}"`), or a custom value.
operation	string	Can be `"equal"`, `"not_equal"`, or `"length"`. If the `"equal"` operator is selected, the condition will be `true` if `"client_value"` equals `"condition_value"`. If the `"not_equal"` operator is selected, the condition will be `true` if `"client_value"` does not equal `"condition_value"`. If the `"length"` operator is selected, the condition will be `true` if the length of the string `"client_value"` is equal to `"condition_value"`.

email/phone condition

The "email" and "phone" conditions check if a string contains a phone number or an email.

{
  "client_value": "{{message_text}}",
  "type": "email",
  "condition_value": "",
  "operation": "contains"
}

Parameter	Data type	Description
client_value	string	The value being checked can be a placeholder from `"show"` handler section, for example, `"{{contact.name}}"`.
type	string	The condition type can be `"email"` for searching an email or `"phone"` for searching a phone number.
condition_value	string	It should be an empty string (`""`).
operation	string	It can be `"contains"` or `"not_contains"`. If the `"contains"` operator is selected, the condition will be `true` if `"client_value"` contains an email or phone number. If the `"not_contains"` operator is selected, the condition will be `true` if `"client_value"` doesn't contain an email or phone number.

regex condition

A "regex" condition checks if a string contains a regular expression.

{
  "client_value": "{{message_text}}",
  "type": "regex",
  "condition_value": "/[0-9]+/",
  "operation": "contains"
}

Parameter	Data type	Description
client_value	string	The value being checked can be a placeholder from `"show"` handler section, for example, `"{{contact.name}}"`.
type	string	It should be "regex".
condition_value	string	Text of the condition.
operation	string	It can be `"contains"` or `"not_contains"`. If the `"contains"` operator is selected, the condition will be `true` if `"client_value"` contains the regular expression. If the `"not_contains"` operator is selected, the condition will be `true` if `"client_value"` doesn't contain the regular expression.

range_numbers condition

A "range_numbers" condition checks if a string contains a number within a specified range.

{
  "client_value": "{{message_text}}",
  "type": "range_numbers",
  "condition_value": {
    "from": 123,
    "to": 321
  },
  "operation": "contains"
}

Parameter	Data type	Description
client_value	string	The value being checked can be a placeholder from `"show"` handler section, for example, `"{{contact.name}}"`.
type	string	It should be `“range_numbers”`.
condition_value	obj	The range in which we check all numbers in `"client_value"`.
condition_value.from	string, number	The `"from"` range value can be specified as a placeholder from `"show"` handler section (for example, `"{{lead.price}}"`), or as a custom value.
condition_value.to	string, number	The `"to"` range value can be specified as a placeholder from `"show"` handler section (for example, `"{{lead.price}}"`), or as a custom value.
operation	string	It can be `"contains"` or `"not_contains"`. If the `"contains"` operator is selected, the condition will be `true` if `"client_value"` contains a number within the specified range. If the `"not_contains"` operator is selected, the condition will be `true` if `"client_value"` doesn't contain a number within the specified range.

preset

The "preset" handler is designed to process incoming messages using predefined templates.

Parameter	Type	Description
name	string	Name of the handler
params	array	Parameters of the handler

contacts.validate_base_info

Preset "contacts.validate_base_info" allows you to obtain and verify information from the user, and then request any missing information.

{
  "handler": "preset",
  "params": {
    "name": "contacts.validate_base_info",
    "params": {
      "empty_email": "Please provide your email.",
      "empty_phone": "Please provide your phone number.",
      "invalid_phone": "It seems that there is a mistake in the phone number.",
      "success": "Thank you",
      "empty_all": "Please provide your email and phone number",
      "check_doubles": true,
      "phone_doubles": "This phone number is already in use. Please enter a different number.",
      "email_doubles": "This email is already in use. Please enter a different email.",
      "all_doubles": "This phone number and email are already in use. Please enter different contact information.",
      "use_quick_replies": true
    }
  }
}

Parameter	Type	Description
empty_email	string	Message in the absence of email from the contact
empty_phone	string	Message in the absence of a phone from a contact
invalid_phone	string	Message when receiving an invalid phone number
success	string	Message after receiving all data
empty_all	string	Message in the absence of all data
check_doubles	bool	A parameter that determines whether to enable the search for duplicate contacts based on email and phone number.If enabled, when a duplicate contact is found, the contact information will be requested again. `true` means enabled, while `false` or absence means disabled.
phone_doubles	string	The message that will be displayed if a duplicate contact is found based on the phone number.
email_doubles	string	The message that will be displayed if a duplicate contact is found based on the email.
all_doubles	string	The message that will be displayed if duplicates are found for the contact based on both the phone number and email.
use_quick_replies	string	A parameter that sends quick reply buttons when the contact is missing an email and/or phone number. This is only available for Facebook and displays buttons containing the user's Facebook account information (phone, email). To enable this feature, set the value to `true`.

contacts.get_base_info

Preset "contacts.get_base_info" allows you to obtain information without asking additional questions.

{
  "handler": "preset",
  "params": {
    "name": "contacts.get_base_info"
  }
}

send_internal

The "send_internal" handler allows you to send an internal message in the lead chat.

🚧
If both group_id and user_id are specified simultaneously, the message will be sent to the group of users.

{
  "handler": "send_internal",
  "params": {
    "entity_id": "{{lead.id}}",
    "entity_type": 2,
    "message": "Hi there!"
  }
}

Parameter	Data type	Description
entity_id	int or string	The ID of the lead the message will be sent to. A placeholder such as `"{{lead.id}}"` can be used.
entity_type	int	A type of the entity the message will be sent to. Only 2 (lead) is available.
message	string	A string with a message
group_id	int	An optional parameter, the ID of the user group to which the message should be sent.
user_id	int	An optional parameter, the ID of the user to whom the message should be sent.

widget_request

The "widget_request: handler is designed to send webhooks to external URLs from Salesbot.

🚧
You can use this handler only from the Widget step of Salesbot.

{
  "handler": "widget_request",
  "params": {
    "url": "https://example.com/endpoint",
    "data": {
      "contact": "{{contact.name}}",
      "from": "widget"
    }
  }
}

Parameter	Data type	Decsription
url	string	The URL endpoint of the external server.
data	array	An array of any data containing strings and/or placeholders from `"show"` handler section, for example, `"{{contact.name}}"`.

The endpoint will receive a POST request. To acknowledge that the webhook has been received, you need to respond within 2 seconds with an HTTP status code 200.

{
      "token": "JWT_TOKEN",
      "data": {
          "contact": "Contact name",
          "from": "widget"
      },
      "return_url": "https://subdomain.kommo.com/api/v4/salesbot/321/continue/123"
    }

The JWT token is needed to validate the data sent in the request. It is signed with the client's secret key.

Widget Response and Resuming Bot Operations

To resume the bot's operation, you need to make a request with the data. The current bot will not continue its operation until it receives the request. Additionally, you will not be able to continue the bot's execution if another bot for the same entity is already running.

stop

The "stop" handler is intended to perform actions when the bot is finished.

{
  "finish": [
    {
      "handler": "stop",
      "params": {
        "action": "talk-close"
      }
    },
    {
      "handler": "stop",
      "params": {
        "action": "salesbot-start",
        "bot": 1234
      }
    }
  ]
}

Parameter	Data type	Description
action	string	It can be `"talk-close"` or `"salesbot-start"`. `"talk-close"` ends the conversation. If this is executed within the NPS bot, the conversation will be closed; otherwise, the NPS bot will be initiated. `"salesbot-start"` launches another bot.
bot	int	The parameter is mandatory if the action selected is `"salesbot-start"`. It specifies the ID of the bot that should be launched.

Examples

Subscribing a group of users to chat.

[
    {
        "question": [
            {
                "handler": "action",
                "params": {
                    "name": "subscribe",
                    "params": {
                        "type": "group",
                        "value": 111
                    }
                }
            }
        ]
    }
]

Moving the lead to another stage.

[
    {
        "question": [
            {
                "handler": "action",
                "params": {
                    "name": "change_status",
                    "params": {
                        "value": 142
                    }
                }
            }
        ]
    }
]

Sending any text to the client:

[
    {
        "question": [
            {
                "handler": "show",
                "params": {
                    "type": "text",
                    "value": "Hello"
                }
            }
        ]
    }
]

Sending a message with the selection buttons:

[
    {
        "question": [
            {
                "handler": "show",
                "params": {
                    "type": "buttons",
                    "value": "Please choose the type of participation:",
                    "buttons": [
                        "Offline",
                        "Online"
                    ]
                }
            }
        ],
        "answer": [
            {
                "handler": "buttons",
                "params": [{
                    "regex": "/offline/iu",
                    "params": [{
                        "handler": "action",
                        "params": {
                            "name": "set_custom_fields",
                            "params": {
                                "type": 2,
                                "value": "Offline",
                                "custom_fields_id": 4242
                            }
                        }
                    }]
                },
                    {
                    "regex": "/online/iu",
                    "params": [{
                        "handler": "action",
                        "params": {
                            "name": "set_custom_fields",
                            "params": {
                                "type": 2,
                                "value": "Online",
                                "custom_fields_id": 4242
                            }
                        }
                    }]
                }]
            }]
    }
]

Setting a tag for a lead:

[
    {
        "question": [
            {
                "handler": "action",
                "params": {
                    "name": "set_tag",
                    "params": {
                        "type": 2,
                        "value": "salesbot"
                    }
                }
            }
        ]
    }
]

Setting a value to a custom field:

[
    {
        "question": [
            {
                "handler": "action",
                "params": {
                    "name": "set_custom_fields",
                    "params": {
                        "type": 2,
                        "custom_fields_id": 123,
                        "value": "Field Value"
                    }
                }
            }
        ]
    }
]

Saving metadata to the lead card.

[
    {
        "question": [
            {
                "handler": "meta",
                "params": {
                    "delimiter": "-",
                    "values": [
                        "lead.tags",
                        "lead.custom_fields.123",
                        "lead.custom_fields.124",
                        "lead.tags"
                    ]
                }
            }
        ]
    }
]

Requesting email and phone number, recording in the lead card only from the first response.

[
    {
        "question": [
            {
                "handler": "show",
                "params": {
                    "type": "text",
                    "value": "Please provide your phone number and email."
                }
            }
        ],
        "answer": [
            {
                "handler": "preset",
                "params": {
                    "name": "contacts.get_base_info"
                }
            }
        ]
    }
]