Salesbot
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 |
| 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 atualcatalog_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. |
subscribe
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 presetcontacts.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}}. |
meta
O manipulador "meta" é projetado para lidar com dados adicionais enviados quando o chat é iniciado.
Para mais informações sobre o envio de metadados, consulte a documentação do mensageiro:
{
"handler": "meta",
"params": {
"delimiter": "-",
"values": [
"lead.tags",
"lead.custom_fields.123",
"lead.custom_fields.124",
"lead.tags"
]
}
}
| 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_idquantouser_idforem 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"
}
}
]
}
]
Updated about 1 month ago