Começando com o Salesbot

Para começar, você precisa conectar a integração com chats na coluna esquerda do Pipeline Digital. As instruções para cada mensageiro estão disponíveis na janela de configurações. Após conectar a integração de chat, você pode ativar o Salesbot para gerenciar novos chats recebidos, bem como configurar bots para etapas específicas.

Configurar o Salesbot

Você pode conectar o Salesbot de duas maneiras:

Acesse a seção Leads ➡️ Automatize ➡️ selecione uma etapa ➡️ Adicionar gatilho ➡️ escolha Robô de vendas.

Em seguida, selecione Criar um novo robô. Na janela modal, você pode optar por um modelo padrão ou criar um bot do zero.

Acesse a seção Configuraçoes ➡️ Ferramentas de comunicação tab ➡️ Salesbots ➡️ Criar ou importar um novo robô.

Na janela modal com os passos do Salesbot, clique em Ver códgio para visualizar o código do bot.

Negócios que entraram na etapa antes da adição da ação no Pipeline Digital serão ignorados, a menos que você marque a opção Aplicar o gatilho à todos os leads já nesta etapa.

Linguagem do Salesbot

O Salesbot utiliza um objeto JSON estruturado com chaves específicas. No exemplo abaixo o bot apresentará a seguinte pergunta, "Por favor, forneça seu número de telefone e e-mail" e adicionará a tag "salesbot". Após a resposta do usuário, o bot validará os dados e responderá com uma das mensagens especificadas. Para mais detalhes sobre predefinições, consulte a próxima seção.

[
    {
        "question": [
            {
                "handler": "show",
                "params": {
                    "type": "text",
                    "value": "Por favor, forneça seu número de telefone e 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": "Por favor, forneça seu e-mail",
                        "empty_phone": "Por favor, forneça seu número de telefone",
                        "invalid_phone": "Parece que o número de telefone pode estar incorreto",
                        "success": "Obrigado",
                        "empty_all": "Por favor, forneça seu número de telefone e e-mail"
                    }
                }
            }
        ]
    }
]

Nos objetos "question", "answer", ou "finish" devem existir handlers (manipuladores).

Os dados no objeto "question" lidam com as ações que ocorrerão quando uma mensagem for enviada ao usuário.
Os dados no objeto "answer" gerenciam as ações que ocorrerão quando o usuário responder.
Os dados no objeto "finish" definem as ações que ocorrerão quando o bot for concluído.

📘
Podem existir múltiplas chaves. No entanto, há uma limitação no tamanho do JSON, que não pode exceder 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.

Manipulador de Erros do Salesbot

Se uma mensagem do bot não puder ser entregue ao cliente, por exemplo, quando o cliente bloqueou mensagens desse chat, o bot pode lidar com o erro e executar manipuladores específicos.

Exemplo:

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

Manipuladores do Salesbot

Código	Descrição
show	Envia uma mensagem com texto
buttons	Processa respostas recebidas de botões em mensageiros instantâneos
action	Ação
meta	Processamento de metadados
condition	Condição
validations	Validação
preset	Processa dados para um algoritmo específico
goto	Transição do script para uma etapa determinada
wait_answer	Aguarda a resposta
find	Pesquisa
filter	Filtragem
send_internal	Envia uma mensagem interna
stop	Interrompe o bot

show

🚧
Este manipulador aceita leads recebidos se configurado no Salesbot.

O manipulador "show" envia uma mensagem ou botões para o chat do cliente. Atualmente, qualquer texto enviado suporta os seguintes placeholders:

Placeholder	Descrição
{{contact.name}}, {{name}}	Nome do contato
{{lead.id}}	ID do Lead
{{contact.id}}	ID do Contato
{{origin}}	Fonte do lead (Telegram, Viber, Facebook)
{{lead.source_id}}	ID da fonte do lead
{{message_text}}	Mensagem recebida do cliente no bloco lógico da resposta
{{lead.cf.#custom_field_id#}}, {{contact.cf.#custom_field_id#}}, {{company.cf.#custom_field_id#}}	Valor do campo personalizado de um lead/contato/empresa (substitua #custom_field_id# pelo ID do campo adicional)
{{rand}}	String aleatória
{{short_rand}}	String aleatória curta
{{short_rand_num}}	Número aleatório de 1111 a 9999
{{message_text.email}}	E-mail (se estiver presente na mensagem do cliente)
{{message_text.phone}}	Número de telefone (se estiver presente na mensagem do cliente)
{{regexp./([1-9]+) things /}}	Valor por expressão regular da resposta do usuário. O valor entre parênteses será substituído e pode ser usado no bloco de resposta
{{lead.price}}	Valor de venda do lead
{{current_date}}	Data atual
{{lead.status_id}}	ID da etapa do lead
{{cf.talk.nps}}	Avaliação da conversa
{{lead.responsible.id}}, {{contact.responsible.id}}, {{company.responsible.id}}	ID do usuário responsável por lead/contato/empresa
{{lead.responsible.name}}, {{contact.responsible.name}}, {{company.responsible.name}}	Nome do usuário responsável por lead/contato/empresa
{{lead.responsible.email}}, {{contact.responsible.email}}, {{company.responsible.email}}	E-mail do usuário responsável por lead/contato/empresa

Para placeholders de contato, é utilizado o contato principal do lead ou o contato do chat em que a comunicação com o cliente está acontecendo.

text

Parâmetros do manipulador para envio de texto.

{
  "handler": "show",
  "params": {
    "type": "text",
    "value": "Por favor, forneça seu número de telefone e e-mail",
    "quick_replies": [
      "user_phone_number",
      "user_email"
    ]
  }
}

Parâmetro	Tipo de dado	Descrição
type	string	Deve ser `"text"`
value	string	Texto a ser enviado ao usuário
quick_replies	array	Array de elementos (atualmente disponíveis: "user_phone_number" e "user_email") para enviar botões de resposta rápida. Disponível apenas para Facebook, exibindo botões com informações da conta do usuário no Facebook (número de telefone, e-mail).

buttons

Parâmetros do manipulador para envio de botões.

{
  "handler": "show",
  "params": {
    "type": "buttons",
    "value": "Escolha o tipo de participação:",
    "buttons": [
      "Presença pessoal",
      "Online"
    ]
  }
}

Parâmetro	Tipo de dado	Descrição
type	string	Deve ser `"buttons"`
value	string	Texto a ser enviado ao usuário (No Messenger, textos com mais de 80 caracteres serão truncados)
buttons	array	Array com os textos dos botões a serem enviados
accept_unsorted	bool	Defina como false caso não precise analisar os leads recebidos na primeira resposta

buttons_url

Parâmetros do manipulador para envio de botões com links para recursos externos.

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

Parâmetro	Tipo de dado	Descrição
type	string	Deve ser `"buttons_url"`. Envia botões com links.
value	string	Texto a ser enviado ao usuário (No Messenger, textos com mais de 80 caracteres serão truncados)
buttons	array	Um array cujos elementos são os textos dos botões que serão enviados

Se você quiser enviar links para redes sociais e habilitar o auto-linking, os links devem estar no seguinte formato:

Mídia social	Link	Comentários
Facebook Messenger	https://m.me/123/?ref=VisitorUid_{{visitor_uid}}	Onde ‘123’ é o ID do grupo
WhatsApp	https://wa.me/7895?text=ID:%20{{session_id}}	Onde ‘7895’ é o número do WhatsApp vinculado à conta.
Viber	viber://pa?chatURI=bot&context=VisitorUid_{{visitor_uid}}	Onde ‘bot’ é o nome da conta pública
Telegram	tg://resolve?domain=bot&start=VisitorUid_{{visitor_uid}}	Onde ‘bot’ é o nome do bot

buttons

O manipulador de botões é projetado para ser inserido no bloco de lógica de resposta e permite processar respostas dos botões enviados ou respostas de correspondência exata.

{
  "handler": "buttons",
  "params": [
    {
      "value": "Presença pessoal",
      "params": [
        {
          "handler": "...",
          "params": {...}
        }
      ]
    },
    {
      "value": "Online",
      "params": [
        {
          "handler": "...",
          "params": {...}
        }
      ]
    }
  ]
}

O manipulador "buttons" espera um array de objetos para inserir nos parâmetros, nos quais qualquer um dos manipuladores especificados nesta página pode ser chamado.

goto

O manipulador goto permite pular para uma etapa específica no cenário, por exemplo, se você precisar realizar certas ações repetidamente.

📘
A contagem das etapas começa a partir de 0.

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

Parâmetro	Tipo de dado	Descrição
type	string	O bloco para o qual o salto será feito. Os valores possíveis são: `"question"`, `"answer"` e `"finish"`.
step	int	A etapa do bot para a qual o salto será feito.

wait_answer

É utilizado para aguardar uma resposta do usuário a uma pergunta específica. Ele permite que você faça uma pergunta ao usuário e espere pela resposta dele antes de prosseguir com outras ações.

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

Parameter	Tipo de dado	Description
type	string	O bloco para o qual o salto será feito. Os valores possíveis são: `"question"` e `"answer"`.
step	int	A etapa do bot para a qual o salto será feito.

find

O manipulador "find" permite localizar uma entidade e usar seus dados. Se um elemento for encontrado, você pode usar os seguintes placeholders:

{{founded_id}} – se um item da lista for encontrado.
{{contact_double.*}} – se um duplicado de contato for encontrado, permitindo acessar seus campos de maneira semelhante ao {{contact.*}} placeholders.

{
  "handler": "find",
  "params": {
    "type": "contact_double",
    "params":{
      "type": "name",
      "actions": [
        {
          "handler": "show",
          "params": {
            "type": "buttons",
            "value": "O número {{contact_double.cf.3574}} é seu?",
            "buttons": [
              "Sim",
              "Não"
            ]
          }
        }
      ]
    }
  }
}

{
  "handler": "find",
  "params": {
  "type": "catalog_elements",
    "params": {
      "value": "Salesbot",
      "catalog_id": "15123",
      "actions": [
        {
          "handler": "show",
          "params": {
            "type": "buttons",
            "value": "An element was found with ID - {{founded_id}}🟥",
            "buttons": [
                "Yes🟥",
                "No🟥"
            ]
          }
        }
      ]
    }
  }
}

Parâmetro	Tipo de dado	Descrição
type	string	`contact_double` – buscar por um duplicado do contato atual `catalog_elements` – buscar por um elemento da lista
params[type]	string	`type` – pode ser `"name"` (a busca está disponível pelo nome; not required for searching by catalog🟥)
params[actions]	array	Ações a serem realizadas se uma entidade for encontrada
value	string	A palavra que está sendo procurada, placeholders do bloco `"show"` podem ser usados. For the `catalog_elements` type – the name of the catalog element🟥.
catalog_id	int	ID da lista onde você está procurando um elemento

filter

O manipulador "filter" permite encontrar uma entidade e usar seus dados. Se um elemento for encontrado, você pode usar os placeholders para os campos personalizados de external_lead e 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"
           }
         }
       }
     ]
   }
 }

Parâmetro	Tipo de dado	Descrição
type	int	O tipo de entidade para a qual o filtro é aplicado: 1 – contato, 2 – lead
value	string	A palavra pela qual filtramos pode incluir placeholders do bloco `"show"`
custom_fields_id	int	O ID do campo personalizado pelo qual o filtro será aplicado

action

O manipulador "action" permite realizar uma das ações possíveis:

Ações	Descrição
unsorted	Ações com Leads de Entrada
change_status	Alteração de etapa
set_tag	Definição de tag
unset_tag	Remoção de tag
set_custom_fields	Definição de valores de campo do lead/contato
subscribe	Inscrição do usuário no chat da entidade
unsubscribe	Cancelamento da inscrição do usuário no chat da entidade
add_lead_contact	Adicionar um lead e um contato vinculados entre si
set_budget	Definir o orçamento do lead (venda)
add_linked_company	Adicionar empresa
add_note	Adicionar uma nota
link	Vincular elementos
change_responsible_user	Alterando pessoas responsável
link_to_unsorted	Criar um contato a partir do lead de entrada e associá-lo ao lead

unsorted

A ação "unsorted" permite aceitar ou rejeitar um Lead de Entrada.

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

Parâmetro	Tipo de dado	Descrição
value	string	`"accept"` / `"decline"` para aceitação/rejeição do lead de entrada.

change_status

A ação "change_status" Permite alterar a etapa do lead.

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

Parâmetro	Tipo de dado	Descrição
value	int	ID da etapa para a qual o lead será transferido.
entity	int or string	Um parâmetro opcional que pode ser `"double"`. Se o manipulador `"find"` foi usado anteriormente, a etapa será atualizada para o lead do contato encontrado, caso exista.

set_tag

A ação "set_tag" atribuirá uma tag ao lead ou contato e suporta o placeholder {{origin}}, que especificará a origem do lead.

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

Parâmetro	Tipo de dado	Descrição
type	int	O tipo de entidade a ser marcada (1-contato, 2-lead)
value	string	Nome da tag

unset_tag

A ação "unset_tag" remove a tag de um negócio ou contato.

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

Parâmetro	Tipo de dado	Descrição
type	int	O tipo de entidade a ser marcada (1-contato, 2-lead)
value	string	Nome da tag que será removida

set_custom_fields

A ação "set_custom_fields" definirá os valores de campos personalizados para um lead ou contato. Você pode encontrar os IDs dos campos na seção Configurações de um lead/contato ou usando o método para obter a lista de campos da entidade. É possível usar placeholders descritos na seção "show" como valores para os campos.

{
  "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}}"
    }
  }
}

Parâmetro	Tipo de dado	Descrição
type	int	O tipo de entidade a ser marcada (1-contato, 2-lead)
value	string	O valor do campo a ser definido pode usar placeholders do bloco `"show"`. Após o manipulador `"validations"`, é permitido usar o placeholder `{{last_validation_result}}`, que usará os dados reconhecidos da última condição `true`. Por exemplo, se a condição `"contains email"` foi usada, o e-mail encontrado será substituído como valor.
custom_fields_id	int	O ID do campo no qual o valor será definido.
custom_field	string	O identificador do campo sendo modificado pode incluir o seguinte: {{lead.price}} – o valor de venda do lead {{lead.name}} – nome do lead {{contact.name}} – nome do contato {{cf.talk.nps}} – a classificação da conversa atual
calculated	bool	Se for necessário tentar calcular o valor desse campo personalizado usando uma fórmula, por exemplo `{{lead.cf.123}} * {{lead.cf.456}}`
option	string	Use a opção `“add”` para adicionar um valor a um campo de sua escolha. Tipos de campo disponíveis: número de telefone, e-mail, lista de seleção múltipla.

A ação "subscribe" irá inscrever um usuário ou grupo de usuários no chat.

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

Parâmetro	Tipo de dado	Descrição
type	string	`"group"` ou `"user"`
value	int	ID do usuário ou grupo de usuários.

unsubscribe

A ação "unsubscribe" irá desinscrever um usuário ou grupo de usuários do chat.

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

Parâmetro	Tipo de dado	Descrição
type	string	`"group"` ,`"user"` ou `"all"`
value	int	ID do usuário ou grupo de usuários. Opcional se `"all"` for passado como `"type"`.

add_lead_contact

A ação "add_lead_contact" criará um lead e um contato e os vinculará. Todos os campos para o lead e o contato podem ser configurados. Os valores dos campos personalizados suportam os mesmos placeholders do manipulador "show". Um "preset" também é suportado, permitindo que o contato e o lead sejam criados somente se uma mensagem ou número de telefone for recebido do cliente.

{
  "handler": "action",
  "params": {
      "name": "add_lead_contact",
      "params": {
          "preset": "contacts.require_email_or_phone",
          "lead": {
              "name": "Nome do lead",
              "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": "Nome do contato",
              "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"
                          }
                      ]
                  }
              ]
          }
      }
  }
}

Parâmetro	Tipo de dado	Descrição
lead	object	Set de campos do lead
contact	object	Set de campos do contato
preset	string	Parâmetro opcional. Um preset `contacts.require_email_or_phone` é suportado, que verifica se o telefone ou email é enviado em uma mensagem do cliente

set_budget

A ação "set_budget" definirá o valor de venda para o lead.

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

Parâmetro	Tipo de dado	Descrição
value	string	Número que será registrado como valor de venda do lead. Este campo também pode ser calculado, permitindo o uso de qualquer placeholder do bloco `"show"` na expressão. Operações disponíveis incluem +, -, _, e /. Também é possível usar parênteses, por exemplo: `({{lead.cf.555123}} + 1){{lead.cf.555321}}`.

add_linked_company

A ação "add_linked_company" adiciona uma empresa vinculada a um lead e a um contato.

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

Parâmetro	Tipo de dado	Descrição
name	string	Nome da empresa, placeholders podem ser usados do bloco `"show"`

add_note

A ação add_note adiciona uma nota

{
  "handler": "action",
  "params": {
    "name": "add_note",
    "params": {
      "element_type": 1,
      "note_type": 4,
      "text": "Texto da nota"
    }
  }
}

Parâmetro	Tipo de dado	Descrição
element_type	int	A entidade à qual a nota será anexada: 1 – contato, 2 – lead
note_type	int	Tipo de nota: 4 – nota comum 10 – Nota de chamada recebida 11 – Nota de chamada efetuada 102 – Nota de mensagem de texto recebida 103 – Nota de mensagem SMS enviada 25 – Nota de serviço
text	string	Texto da nota, placeholders do bloco `"show"` podem ser usados nela

link

A ação "link" vincula elementos.

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

Parâmetro	Tipo de dado	Descrição
from	int	A entidade à qual a segunda entidade será vinculada (1 – contato, 2 – lead)
from_id	int	Parâmetro opcional. O ID da entidade à qual a segunda entidade será vinculada. Se não especificado, o ID da entidade atual será usado. Placeholders da seção "show" também podem ser usados.
to	int	A entidade a ser vinculada: 1 – contato, 2 – lead, 3 – empresa, 11 – elemento de lista.
to_id	string	ID do elemento a ser vinculado, você pode usar os placeholders da seção `"show"`
to_catalog_id	int	Parâmetro opcional, ID da lista (se o elemento da lista for vinculado)
quantity	int	Parâmetro opcional, número de elementos da lista a serem anexados à entidade. Placeholders da seção `"show"` podem ser usados.

change_responsible_user

A ação change_responsible_user altera o usuário responsável por um lead ou pelo contato associado.

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

Parâmetro	Tipo de dado	Descrição
value	int	ID do usuário que você deseja definir como responsável
type	int	Parâmetro opcional, o tipo de entidade para a qual o usuário responsável está sendo alterado: 1 – contato, 2 – lead. Se não fornecido, o padrão é 2.

link_to_unsorted

A ação "link_to_unsorted" vincula um chat de leads recebidos ao contato especificado em um lead. Se o contato especificado não existir no lead, o vínculo não ocorrerá. Se contact_id não for fornecido, um contato será criado no lead especificado.

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

Parâmetro	Tipo de dado	Descrição
entity_type	int	Tipo de entidade (2 – lead)
entity_id	string	O ID da entidade à qual o contato deve ser vinculado. Placeholders podem ser usados, por exemplo, se um manipulador `"filter"` foi usado, você pode usar `{{external_lead.id}}`.
contact_id	string	Parâmetro opcional. O ID do contato ao qual o chat deve ser vinculado. O contato deve estar no lead especificado. Placeholders podem ser usados, por exemplo, se um manipulador `"filter"` foi usado, você pode usar `{{external_contact.id}}`.

Parâmetro	Tipo de dado	Descrição
delimiter	string	O caractere que separará o conteúdo recebido em elementos.
values	array	Um array de valores onde os elementos das informações recebidas serão armazenados. Os valores podem ser registrados em tags ou campos do lead.

condition

O manipuldor "condition" é projetado para criar condições lógicas.

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

Parâmetro	Tipo de dado	Descrição
term1	string	A condição 1 pode ser: `lead.tags` – que retorna uma lista de tags, `chat.origin` – que retorna a origem de onde a solicitação veio (Facebook, Telegram, Viber), qualquer placeholder do bloco descrito na seção do manipulador `"show"`, por exemplo `{{contact.name}}`
term2	string/obj	Condição 2: para o operador `in_range`, é necessário passar um objeto com parâmetros; caso contrário, uma string ou placeholder da seção do manipulador `"show"` deve ser fornecido.
term2.from	int	O valor “de” do intervalo.
term2.to	int	O valor “para” do intervalo.
operation	string	O operador de comparação: `"="`, `"! ="`, `"in"`, `"not_in"`, ou `"in_range"`
result	array	Se a comparação for bem-sucedida, o array de manipuladores.

Operadores

Operador	Descrição
`"="`	O operador "=" verifica se `"term1"` é igual a `"term2"`
`"!="`	O operador "!=" verifica se `"term1"` não é igual a `"term2"`
`"in"`	Ele pega as strings de `"term1"` e `"term2"`, divide-as em valores separados por vírgulas e procura ocorrências dos valores de `"term2"` em `"term1"`. Se houver pelo menos uma correspondência, os manipuladores de resultado serão executados.
`"not_in"`	Ele pega as strings de `"term1"` e `"term2"`, divide-as em valores separados por vírgulas e procura ocorrências dos valores de `"term2"` em `"term1"`. Se não houver correspondências, os manipuladores de resultado serão executados.
`"in_range"`	Ele encontra todos os números inteiros em `"term1"`. Se pelo menos um desses números cair dentro do intervalo especificado por `"term2"`, o array de manipuladores de resultado será executado.

validations

O manipulador "validations" é projetado para criar condições lógicas.

{
  "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
        }
      }
    ]
  }
}

Parâmetro	Tipo de dado	Descrição
logic	string	A lógica para verificar as condições é a seguinte: se `"and"` for especificado, todas as condições devem ser verdadeiras; se `"or"` for especificado, pelo menos uma das condições deve ser verdadeira.
conditions	array	A lista de condições para verificação é descrita abaixo.
result	array	Após a validação bem-sucedida, o array de manipuladores será executado.

simple condition

A condição "simple" verifica a igualdade/desigualdade ou compara o comprimento.

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

Parâmetro	Tipo de dado	Descrição
client_value	string	O valor sendo verificado pode ser um placeholder da seção `"show"`, por exemplo `"{{contact.name}}"`.
type	string	Deve ser definido como `"simple"`
condition_value	string	Pode ser um placeholder da seção `"show"` (por exemplo, `"{{contact.name}}"`), ou um valor personalizado.
operation	string	Pode ser `"equal"`, `"not_equal"`, ou `"length"`. Se o operador `"equal"` for selecionado, a condição será `true` se `"client_value"` for igual a `"condition_value"`. Se o operador `"not_equal"` for selecionado, a condição será `true` se `"client_value"` for diferente de `"condition_value"`. Se o operador `"length"` for selecionado, a condição será `true` se o comprimento da string `"client_value"` for igual a`"condition_value"`.

email/phone condition

As condições "email" e "phone" verificam se uma string contém um número de telefone ou um email.

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

Parâmetro	Tipo de dado	Descrição
client_value	string	O valor sendo verificado pode ser um placeholder da seção `"show"`, por exemplo, `"{{contact.name}}"`.
type	string	O tipo de condição pode ser `"email"` para buscar um email ou `"phone"` para buscar um número de telefone.
condition_value	string	Deve ser uma string vazia (`""`).
operation	string	Pode ser `"contains"` ou `"not_contains"`. Se o operador `"contains"` for selecionado, a condição será `true` se `"client_value"` contiver um email ou número de telefone. Se o operador `"not_contains"` for selecionado, a condição será `true` se `"client_value"` não contiver um email ou número de telefone.

regex condition

A condição "regex" verifica se uma string contém uma expressão regular.

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

Parâmetro	Tipo de dado	Descrição
client_value	string	O valor sendo verificado pode ser um placeholder da seção `"show"`, por exemplo, `"{{contact.name}}"`.
type	string	Deve ser definido como "regex".
condition_value	string	Texto da condição
operation	string	Pode ser `"contains"` ou `"not_contains"`. Se o operador `"contains"` for selecionado, a condição será `true` se `"client_value"` contiver a expressão regular. Se o operador `"not_contains"` for selecionado, a condição será `true` se `"client_value"` não contiver a expressão regular.

range_numbers condition

A condição "range_numbers" verifica se uma string contém um número dentro de um intervalo especificado.

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

Parâmetro	Tipo de dado	Descrição
client_value	string	O valor sendo verificado pode ser um placeholder da seção `"show"`, por exemplo, `"{{contact.name}}"`.
type	string	Deve ser definido como `“range_numbers”`.
condition_value	obj	O intervalo no qual verificamos todos os números em `"client_value"`.
condition_value.from	string, number	O valor do intervalo `"from"` pode ser especificado como um placeholder da seção `"show"` (por exemplo, `"{{lead.price}}"`), ou como um valor personalizado.
condition_value.to	string, number	O valor do intervalo `"to"` pode ser especificado como um placeholder da seção `"show"` (por exemplo, `"{{lead.price}}"`), ou como um valor personalizado.
operation	string	Pode ser `"contains"` ou `"not_contains"`. Se o operado `"contains"` for selecionado, a condição será `true` se `"client_value"` contiver um número dentro do intervalo especificado. Se o operador `"not_contains"` for selecionado, a condição será `true` se `"client_value"` não contiver um número dentro do intervalo especificado.

preset

O manipulador "preset" foi projetado para processar mensagens recebidas usando modelos predefinidos.

Parâmetro	Tipo de dado	Descrição
name	string	Nome do manipulador
params	array	Parâmetros do manipulador

contacts.validate_base_info

O modelo "contacts.validate_base_info" permite obter e verificar informações do usuário e, em seguida, solicitar qualquer informação faltante.

{
  "handler": "preset",
  "params": {
    "name": "contacts.validate_base_info",
    "params": {
      "empty_email": "Por favor, forneça seu e-mail.",
      "empty_phone": "Por favor, forneça seu número de telefone.",
      "invalid_phone": "Parece que há um erro no número de telefone.",
      "success": "Obrigado.",
      "empty_all": "Por favor, forneça seu e-mail e número de telefone.",
      "check_doubles": true,
      "phone_doubles": "Este número de telefone já está em uso. Por favor, insira um número diferente.",
      "email_doubles": "Este e-mail já está em uso. Por favor, insira um e-mail diferente.",
      "all_doubles": "Este número de telefone e e-mail já estão em uso. Por favor, insira informações de contato diferentes.",
      "use_quick_replies": true
    }
  }
}

Parâmetro	Tipo de dado	Descrição
empty_email	string	Mensagem na ausência de e-mail do contato
empty_phone	string	Mensagem na ausência de telefone de um contato
invalid_phone	string	Mensagem ao receber um número de telefone inválido
success	string	Mensagem após receber todos os dados
empty_all	string	Mensagem na ausência de todos os dados
check_doubles	bool	Um parâmetro que determina se deve habilitar a busca por contatos duplicados com base no e-mail e número de telefone. Se habilitado, ao encontrar um contato duplicado, as informações de contato serão solicitadas novamente. `true` significa habilitado, enquanto `false` ou ausência significa desabilitado.
phone_doubles	string	A mensagem que será exibida se um contato duplicado for encontrado com base no número de telefone.
email_doubles	string	A mensagem que será exibida se um contato duplicado for encontrado com base no e-mail.
all_doubles	string	A mensagem que será exibida se forem encontrados duplicados para o contato com base tanto no número de telefone quanto no e-mail.
use_quick_replies	string	Um parâmetro que envia botões de resposta rápida quando o contato estiver sem e-mail e/ou número de telefone. Isso está disponível apenas para o Facebook e exibe botões contendo as informações da conta do usuário no Facebook (telefone, e-mail). Para habilitar esse recurso, defina o valor como `true`.

contacts.get_base_info

O modelo "contacts.get_base_info" permite obter informações sem fazer perguntas adicionais.

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

send_internal

O manipulador "send_internal" permite enviar uma mensagem interna no chat do lead.

🚧
Se tanto group_id quanto user_id forem especificados simultaneamente, a mensagem será enviada para o grupo de usuários.

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

Parâmetro	Tipo de dado	Descrição
entity_id	int or string	O ID do lead para o qual a mensagem será enviada. Um marcador de posição, como `"{{lead.id}}"`, pode ser usado.
entity_type	int	O tipo da entidade para a qual a mensagem será enviada. Somente 2 (lead) está disponível.
message	string	Uma string com a mensagem.
group_id	int	Um parâmetro opcional, o ID do grupo de usuários para o qual a mensagem deve ser enviada.
user_id	int	Um parâmetro opcional, o ID do usuário para o qual a mensagem deve ser enviada.

widget_request

O manipulador "widget_request: é projetado para enviar webhooks para URLs externas do Salesbot.

🚧
Você pode usar esse manipulador apenas a partir do passo Widget do Salesbot. Encontre informações adicionais sobre o widget no Salesbot aqui.

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

onSalesbotDesignerSave: function (handler_code, params) {
  var request_data = {
    message: params.message,
  };

  if (APP.getBaseEntity() === 'lead') {
    request_data.lead = '{{lead.id}}';
  };

  return JSON.stringify([
    {
      question: [
        {
          handler: 'widget_request',
          params: {
            url: 'https://example.com/webhook',
            data: request_data,
          },
        },
        {
          handler: 'goto',
          params: {
            type: 'question',
            step: 1,
          },
        },
      ],
    },
    {
      question: [
        {
          handler: 'conditions',
          params: {
            logic: 'and',
            conditions: [
              {
                term1: '{{json.status}}',
                term2: 'success',
                operation: '=',
              },
            ],
            result: [
              {
                handler: 'exits',
                params: {
                  value: 'success',
                },
              },
            ],
          },
        },
        {
          handler: 'exits',
          params: {
            value: 'fail',
          },
        },
      ],
    },
  ]);
},

Parâmetro	Tipo de dado	Descrição
url	string	O endpoint da URL do servidor externo.
data	array	Um array de quaisquer dados contendo strings e/ou marcadores de posição da seção `"show"` do manipulador, por exemplo, `"{{contact.name}}"`.

O endpoint receberá uma requisição POST. Para confirmar que o webhook foi recebido, é necessário responder dentro de 2 segundos com o código de status HTTP 200.

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

O JWT token é necessário para validar os dados enviados na requisição. Ele é assinado com a chave secreta do cliente.

Resposta do Widget e Retomada das Operações do Bot

Para retomar a operação do bot, é necessário fazer uma requisição com os dados. O bot atual não continuará sua operação até receber a requisição. Além disso, você não poderá continuar a execução do bot se outro bot para a mesma entidade já estiver em execução.

stop

O manipulador "stop" é destinado a realizar ações quando o bot terminar.

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

Parâmetro	Tipo de dado	Descrição
action	string	Pode ser `"talk-close"` ou `"salesbot-start"`. `"talk-close"` encerra a conversa. Se isso for executado dentro do bot NPS, a conversa será encerrada; caso contrário, o bot NPS será iniciado. `"salesbot-start"` inicia outro bot.
bot	int	O parâmetro é obrigatório se a ação selecionada for `"salesbot-start"`. Ele especifica o ID do bot que deve ser iniciado.

Exemplos

Assinando um grupo de usuários para o chat.

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

Movendo o lead para outro estágio.

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

Enviando qualquer texto para o cliente:

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

Enviando uma mensagem com os botões de seleção:

[
    {
        "question": [
            {
                "handler": "show",
                "params": {
                    "type": "buttons",
                    "value": "Por favor, escolha o tipo de participação:",
                    "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
                            }
                        }
                    }]
                }]
            }]
    }
]

Definindo uma tag para um lead:

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

Definindo um valor para um campo personalizado:

[
    {
        "question": [
            {
                "handler": "action",
                "params": {
                    "name": "set_custom_fields",
                    "params": {
                        "type": 2,
                        "custom_fields_id": 123,
                        "value": "Valor do campo"
                    }
                }
            }
        ]
    }
]

Salvando metadados no cartão do lead.

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

Solicitando e-mail e número de telefone, gravando no cartão do lead apenas a partir da primeira resposta.

[
    {
        "question": [
            {
                "handler": "show",
                "params": {
                    "type": "text",
                    "value": "Por favor, forneça seu número de telefone e e-mail."
                }
            }
        ],
        "answer": [
            {
                "handler": "preset",
                "params": {
                    "name": "contacts.get_base_info"
                }
            }
        ]
    }
]