Salesbot
Getting Started with Salesbot
Salesbot is a bot that can be programmed to perform certain actions. It helps to receive data from users via messengers (Telegram, Facebook Messenger, Viber).
To get started, you need to connect the integration with chats in the left column of the Digital pipeline. Instructions for each of the messengers you will find in the settings window. After connecting the integration with the chat rooms, you can activate Salesbot to handle incoming new chats, and configure bots for certain statuses.
Connecting integration with chat rooms and configuring Salesbot for incoming calls to the Digital Pipeline
To configure Salesbot for incoming messages, click on the Salesbot label on the left side of the Digital pipeline.
Move the switch to the on position, and in the input field command or use one of the available workpieces.
Connecting integration with chat rooms and configuring Salesbot for incoming calls to the Digital Pipeline.
To configure Salesbot in statuses, click the add action button and in the window that opens, click the “Salesbot” button.
You can choose one of the conditions for the duration of the action, or specify an exact implementation date.
Attention! Leads in the status before the action in the Digital pipeline will be ignored.
Configuring Salesbot in the status in the Digital Pipeline
Salesbot in statuses can be written in the form of a regular message that will be sent to the user, or as a special code that will make the bot work more interactive and perform certain business tasks. Salesbot supports only special code for processing incoming messages.
Salesbot language
The management language of Salesbot is a structured JSON object with specific keys.
The example below will ask the question “Inform, please, your telephone number and e-mail” and put the tag of the Salesbot lead.
After the user responds, he will validate the data and reply with one of the specified messages. For more information about presets, see the next section.
[
{
"question": [
{
"handler": "show",
"params": {
"type": "text",
"value": "Please tell your phone number and e-mail"
}
},
{
"handler": "action",
"params": {
"name": "set_tag",
"params": {
"type": 2,
"value": "salesbot"
}
}
}
],
"answer": [
{
"handler": "preset",
"params": {
"name": "contacts.validate_base_info",
"params": {
"empty_email": "Please send your e-mail",
"empty_phone": "Please send your phone number",
"invalid_phone": "It seems to us that the phone number is incorrect",
"success": "Thank you",
"empty_all": "Please send your phone number and e-mail"
}
}
}
]
}
]The object must have a question or answer key.
The data in the question object is responsible for the actions that will occur when the message is sent to the user.
The data in the answer object is responsible for the actions that will occur when the user answers.
The question or answer key may be more than one. However, there is a limit on the size of JSON, no more than 64K.
The question or answer object must contain processing. The handler is an object with the keys handler and params.
Before adding a JSON object to the bot, check it for validity.
You can also get a valid object using PHP. You need to create an array of Salesbot, and then apply the function
json_encode with the flags JSON_PRETTY_PRINT and JSON_UNESCAPED_UNICODE.
Example:
$bot_text = 'Hello World!';
$salesbot = [
[
'question' => [
[
'handler' => 'show',
'params' => [
'type' => 'text',
'value' => $bot_text
]
]
],
'answer' => [
[
'handler' => 'preset',
'params' => [
'name' => 'contacts.get_base_info',
]
]
]
]
];
echo json_encode($salesbot, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
The result of the code above will be a valid JSON object, ready for insertion into the Salesbot’s Digital Pipeline.
The Salesbot Error Handler
If the message from the bot can not be delivered to the client, for example, when the client has blocked messages from this chat. The bot can handle the error, and execute any 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 |
| preset | Processes data for a specific algorithm |
| goto | Transition of the script to a certain step |
| find | Search |
| filter | Filtration |
The show handler
Attention! This handler accepts an unparsed handler, in case it is configured in Salesbot’s incoming orders.
The show handler sends a message or buttons to the chat with the client
Any sent text currently supports the following markup elements:
-
{{contact.name}}, {{name}} – set the name of the contact
-
{{lead.id}} – Set lead id
-
{{origin}} – installation of the source of the lead (telegram,viber, facebook)
-
{{message_text}} – received client message in the response logic
-
{{lead.cf. # custom_field_id #}} – set the value of the custom lead field, instead of # custom_field_id # substitute the id of the additional field
-
{{contact.cf. # custom_field_id #}} – set the value of the custom field of the contact, instead of # custom_field_id # substitute the id of the additional field
-
{{rand}} – setting of a random string
-
{{message_text.email}} – setting up email, if it exists in a message from the client
-
{{message_text.phone}} – installation of the phone, if it exists in the message from the client
-
{{regexp./([§]+) things /}} – sets the value of the regular expression from the user’s response. Substitute the value from the parentheses. Can be used in the answer block
-
{{lead.price}} – Set lead budget
-
{{current_date}} – setting the current date
-
{{short_rand}} – setting a short random string
-
{{lead.status_id}} – set status id
Parameters of the handler for sending text
Example:
{
"handler": "show",
"params": {
"type": "text",
"value": "Please tell us your phone number and e-mail"
}
}| Parameter | Type | Description |
|---|---|---|
| type | text | Send text or buttons |
| value | string | Text to be sent to the user |
Parameters of the handler for sending buttons
Example
{
"handler": "show",
"params": {
"type": "buttons",
"value": "Please choose the type of participation:",
"buttons": [
"Personal presence",
"Online"
]
}
}| Parameter | Type | Description |
|---|---|---|
| type | button | Send text or buttons |
| 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 |
| accept_unsorted | bool | Set to false if you do not need to parse the unresolved at the first response |
The buttons handler
The button handler is intended for insertion into the logical block of the response and allows to process the response from the sent buttons or the answer by exact match
Example
{
"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
The goto handler
The goto handler allows you to go to the desired step in the script, for example, if you need to cycle through some actions. We draw your attention to the fact that the counting of the stages is carried out with 0.
Example
{
"handler": "goto",
"params": {
"type": "question",
"step": 3
}
}| Parameter | Type | Description |
|---|---|---|
| type | string | In which block the transition will be made. Possible values of “question” and “answer” |
| step | int | On which step of the bot the transition will be made |
The find handler
The find handler lets you find the entity and use its data. If an element is found, you can use the {{founded_id}}
Example
{
"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 | Type | Description |
|---|---|---|
| type | string |
contact_double – search for a duplicate of the current contact catalog_elements – search for a catalog entry |
| params | array | type – can be name (search is available by name), actions – actions to be performed if an entity was found |
| value | string | The word that is looking for, markers from the SHOW block can be used |
| catalog_id | int | Id directory – in which we are looking for elements |
The filter handler
The filter handler allows you to find the entity and use its data. If an element is found, it can be used in markers by custom fields external_lead and external_contact
Example
{
"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 | Type | Description |
|---|---|---|
| type | int | The type of the entity on which the filter operates: 1 – contact, 2 – lead |
| value | string | The word on which we filter can be used markers from the SHOW block |
| custom_fields_id | int | Id of the custom field on which the filter will be produced |
Action handler
The action handler allows you to perform one of the possible actions
| Code | Description |
|---|---|
| unsorted | Actions with Incoming Leads |
| change_status | Change of status |
| set_tag | Setting the tag |
| unset_tag | Deleting a tag |
| set_custom_fields | Setting lead / contact field values |
| subscribe | Subscribing a group of users to chat in entity |
| add_lead_contact | Adding a lead and a contact related to each other |
| set_budget | Setting the leads budget |
| add_linked_company | Add company |
| add_note | Add a note |
| link | Associates elements |
| change_responsible_user | Changes the responsible person |
Action unsorted
The unsorted action allows you to accept or reject an Incoming Lead
Example
{
"handler": "action",
"params": {
"name": "unsorted",
"params": {
"value": "accept"
}
}
},
{
"handler": "action",
"params": {
"name": "unsorted",
"params": {
"value": "decline"
}
}
}| Parameter | Type | Description |
|---|---|---|
| value | string | accept / decline for acceptance / decline |
Action change_status
The action change_status allows you to change the status of the lead
Example:
{
"handler": "action",
"params": {
"name": "change_status",
"params": {
"value": 142
}
}
}| Parameter | Type | Description |
|---|---|---|
| value | int | id of the status to which the lead will be transferred |
| entity | int | not a required parameter, it can be double, if the find function was used before, then the status will change in the lead of the found match, if it exists |
Action set_tag
The set_tag action will set the trade or contact tag, has the {{origin}} layout support, which will put the lead
Example:
{
"handler": "action",
"params": {
"name": "set_tag",
"params": {
"type": 2,
"value": "Salesbot"
}
}
},
{
"handler": "action",
"params": {
"name": "set_tag",
"params": {
"type": 2,
"value": "{{origin}}"
}
}
}| Parameter | Type | Description |
|---|---|---|
| type | int | The type of entity to be tagged (1-contact, 2-leads) |
| value | string | name of a tag |
Unset_tag action
The unset_tag action removes the tag from a trade or contact
Example:
{
"handler": "action",
"params": {
"name": "unset_tag",
"params": {
"type": 2,
"value": "Salesbot"
}
}
}| Parameter | 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 |
Action set_custom_fields
The set_custom_fields action will set the lead or the contact to the values of the custom fields.
You can find the field IDs in the Settings-> Fields section or using the GET accounts / current method. You can use the markers described in the section “The show handler”
Example:
{
"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
}
}
}| Parameter | Type | Description |
|---|---|---|
| type | int | The type of entity to be tagged (1-contact, 2-leads) |
| value | string | The value of the field to be set |
| custom_fields_id | int | id of the field to which the value will be set |
| calculated | bool | Is it 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 |
Action subscribe
The subscribe action will sign a group of users to chat
Example
{
"handler": "action",
"params": {
"name": "subscribe",
"params": {
"type": "group",
"value": 111
}
}
}| Parameter | Type | Description |
|---|---|---|
| type | string | At the moment it should be group |
| value | int | id of a group of users |
Action add_lead_contact
The action add_lead_contact will add the deal and the contact and link them together. All lead and contact fields can be customized. The values of custom fields are supported by the markup, which is the same as in the show handler. The preset is also supported, so that a contact and a lead can be created only if a message or phone is received from the client.
Example:
{
"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": 77744333,
"values": [
{
"value": "{{rand}}"
}
]
},
{
"id": 77744444,
"values": [
{
"value": "{{message_text.email}}",
"enum": "WORK"
}
]
},
{
"id": 77744555,
"values": [
{
"value": "{{message_text.phone}}",
"enum": "WORK"
}
]
}
]
}
}
}
}| Parameter | 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 transmitted in a message from the client |
Action set_budget
The set_budget action will set the budget for the lead
Example
{
"handler": "action",
"params": {
"name": "set_budget",
"params": {
"value": "{{lead.cf.555123}}*{{lead.cf.555321}}"
}
}
}| Parameter | Type | Description |
|---|---|---|
| value | string | The number that will be recorded in the budget of the lead. Available operations: +, -, *, /, you can also use parentheses for example: {{lead.cf.555123}}*{{lead.cf.555321}} |
Action add_linked_company
Add_linked_company action Adds a company tied to a deal and a contact
Example
{
"handler": "action",
"params": {
"name": "add_linked_company",
"params": {
"name": "{{message_text}}"
}
}
}| Parameter | Type | Description |
|---|---|---|
| name | string | Company name, markers can be used from the SHOW block |
Add_note action
Add_note action adds a note
Example
{
"handler": "action",
"params": {
"name": "add_note",
"params": {
"element_type": 1,
"note_type": 4,
"text": "Note text"
}
}
}| Parameter | Type | Description |
|---|---|---|
| element_type | int | The essence to which the note will be attached: 1 – contact, 2 – lead |
| note_type | int |
Type of note: 4 – the usual note 10 – Incoming call note 11 – Outgoing call note 102 – Note for an incoming text message 103 – Outgoing SMS message note 25 – Service note |
| text | string | Note text, markers from the SHOW block can be used in it |
Action link
The action link will add a note
Example
{
"handler": "action",
"params": {
"name": "link",
"params": {
"from": 2,
"to": 11,
"to_id": "{{founded_id}}",
"to_catalog_id": 123
}
}
}| Parameter | Type | Description |
|---|---|---|
| from | int | The essence to which the fixing will be done: 1 – contact, 2 – lead |
| to | int | The essence of the attachment: 1 – contact, 2 – lead, 11 – element of the catalog, 3 – company |
| to_id | string | Id of the element to be attached, you can use the markers from the SHOW section |
| to_catalog_id | int | An optional parameter, directory id – if the directory element is bound |
Action change_responsible_user
The action change_responsible_user changes the responsible
{
"handler": "action",
"params": {
"name": "change_responsible_user",
"params": {
"value": 123
}
}
}| Parameter | Type | Description |
|---|---|---|
| value | int | id of the user you want to make responsible |
The meta handler
The meta handler is designed to handle additional data that is sent when the chat starts
For more information about sending meta-data, see the messenger documentation:
-
Telegram
-
Viber
-
Messenger
Example
{
"handler": "meta",
"params": {
"delimiter": "-",
"values": [
"lead.tags",
"lead.custom_fields.123",
"lead.custom_fields.124",
"lead.tags"
]
}
}| Parameter | Type | Description |
|---|---|---|
| delimiter | string | The symbol by which incoming content will be divided into elements |
| values | array | An array of values in which elements of incoming information will be written. Values can be written in tags or lead fields |
Condition handler
The condition handler is designed to create logical conditions
Example
{
"handler": "condition",
"params": {
"term1": "lead.tags",
"term2": "telegram",
"operation": "=",
"result": [
{
"handler": "action",
"params": {
"name": "change_status",
"params": {
"value": 123
}
}
}
]
}
}| Parameter | Type | Description |
|---|---|---|
| term1 | string | Condition 1 can be lead.tags – which returns a list of tags, chat.origin – which returns the source from where the application came from (facebook, telegram, viber) any handler from the block described in the SHOW section, for example {{contact.name}} |
| term2 | string | Condition 2, you can use the markers from the SHOW block |
| operation | string | The comparison operator (‘=’ or ‘! =’) |
| result | array | If the comparison is successful, the array of handlers |
The preset handler
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 |
Preset contacts.validate_base_info
Preset contacts.validate_base_info allows you to get and verify information from the user, and then ask the missing
Example
{
"handler": "preset",
"params": {
"name": "contacts.validate_base_info",
"params": {
"empty_email": "Please send your e-mail",
"empty_phone": "Please send your phone number",
"invalid_phone": "It seems to us that the phone number is a mistake",
"success": "Thank you.",
"empty_all": "Please send your phone number and e-mail"
}
}
}| 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 |
Preset contacts.get_base_info
Preset contacts.get_base_info allows you to get information, this preset does not ask additional questions
Example
{
"handler": "preset",
"params": {
"name": "contacts.get_base_info"
}
}Examples
Subscribing a group of users to chat.
Example
[
{
"question": [
{
"handler": "action",
"params": {
"name": "subscribe",
"params": {
"type": "group",
"value": 111
}
}
}
]
}
]Lead of the lead to the desired status.
Example
[
{
"question": [
{
"handler": "action",
"params": {
"name": "change_status",
"params": {
"value": 142
}
}
}
]
}
]Sending any text to the client
Example
[
{
"question": [
{
"handler": "show",
"params": {
"type": "text",
"value": "Hello"
}
}
]
}
]Sending a message with the selection buttons
Example
[
{
"question": [
{
"handler": "show",
"params": {
"type": "buttons",
"value": "Please choose the type of participation:",
"buttons": [
"Personal presence",
"Online"
]
}
}
],
"answer": [
{
"handler": "buttons",
"params": [{
"regex": "/personal/iu",
"params": [{
"handler": "action",
"params": {
"name": "set_custom_fields",
"params": {
"type": 1,
"value": "Personal presence",
"custom_fields_id": 4242
}
}
}]
},
{
"regex": "/online/iu",
"params": [{
"handler": "action",
"params": {
"name": "set_custom_fields",
"params": {
"type": 1,
"value": "Online",
"custom_fields_id": 4242
}
}
}]
}]
}]
}
]Set the tag for the lead
Example
[
{
"question": [
{
"handler": "action",
"params": {
"name": "set_tag",
"params": {
"type": 2,
"value": "salesbot"
}
}
}
]
}
]Set the value to an additional field.
Example
[
{
"question": [
{
"handler": "action",
"params": {
"name": "set_custom_fields",
"params": {
"type": 2,
"custom_fields_id": 123,
"value": "Field Value"
}
}
}
]
}
]Preservation of metadata in the lead card
Example
[
{
"question": [
{
"handler": "meta",
"params": {
"delimiter": "-",
"values": [
"lead.tags",
"lead.custom_fields.123",
"lead.custom_fields.124",
"lead.tags"
]
}
}
]
}
]Request email and phone, write to the card only from the first answer.
Example
[
{
"question": [
{
"handler": "show",
"params": {
"type": "text",
"value": "Please tell us your phone number and e-mail"
}
}
],
"answer": [
{
"handler": "preset",
"params": {
"name": "contacts.get_base_info"
}
}
]
}
]