# Construtor de API

Algumas funções de solicitação de API podem ser executadas na Calculadora.

As solicitações são enviadas via **POST** ou **GET** método para uma URL no seguinte formato:

**<https://chatter.mavibot.ai/api/{api\\_key}/{action}>**

Onde:

**api\_key** — a chave de acesso da API gerada nas configurações do projeto.

<figure><img src="/files/b4d89b640df7d60d83826f548a37026b43e82b61" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
Para usar o token em uma solicitação de URL, primeiro você precisa gerar uma chave de API.

As instruções para fazer isso estão na seção "Gerando uma Chave de API". <mark style="color:vermelho;">**ссылка**</mark>
{% endhint %}

{% hint style="danger" %}
Ao copiar uma URL desta página, pode aparecer um espaço e ele deve ser removido.

Exemplo de link incorreto:
&#x20;<https://chatter.mavibot.pro> /api/callback

Se o espaço após .pro permanecer, a solicitação não vai funcionar.
{% endhint %}

{% hint style="warning" %}
Não use caracteres proibidos ao enviar uma solicitação GET.

Certifique-se de entender o formato correto para solicitações GET.
{% endhint %}

## **Como gerar uma chave de API**

{% hint style="success" %}
O recurso antigo de geração de chave de API ainda funciona como antes, mas não está disponível para novos projetos.

Se o seu projeto já tiver chaves de API geradas sem as configurações de acesso descritas nesta seção, essas chaves de API existentes continuarão funcionando normalmente.

Se você precisar gerar novas chaves, use as configurações atualizadas.
{% endhint %}

Para gerar uma chave de API, vá para as configurações do projeto:

<figure><img src="/files/786eef14fb3e1ea1cc912e828972e3820a0e7eb3" alt="" width="301"><figcaption></figcaption></figure>

Em seguida, vá para a seção "Integrações":

<figure><img src="/files/b69eb38900b69d60d1f22e7b734ed9bf30899aa0" alt="" width="563"><figcaption></figcaption></figure>

Você encontrará o botão “Adicionar chave de API” na seção "Integrações":

<figure><img src="/files/9b27763766ffeae01da71d8108a7060142baf49b" alt=""><figcaption></figcaption></figure>

Depois de clicar no botão, uma janela modal será aberta com as configurações de acesso e as opções de geração de chave de API:

<figure><img src="/files/72c6c5cecb679b7f7859ca02180ca1eee609d1bd" alt=""><figcaption></figcaption></figure>

Em seguida, você precisa selecionar as permissões de acesso para a chave de API:

<figure><img src="/files/a6907c6c43091f61488687cc338496860a0a52f6" alt=""><figcaption></figcaption></figure>

A função da API funcionará de acordo com as permissões de acesso que você selecionar.

{% hint style="warning" %}
Por favor, observe!

A função da API depende das permissões de acesso que você definir: se você gerar uma chave de API com acesso somente leitura às informações do cliente e depois usá-la para enviar uma mensagem a um cliente ou modificar suas variáveis, a solicitação da API falhará.
\
A permissão necessária para cada solicitação de API é especificada no cartão da solicitação de API:

<img src="/files/57c9481ce3591d65910725b10115fb2d2307ddae" alt="" data-size="original">
{% endhint %}

Em seguida, digite um nome para a chave de API:

<figure><img src="/files/d9ad2c6db92ba9fb8cbe132c7c8e933d9221932c" alt=""><figcaption></figcaption></figure>

Gere a chave de API clicando no botão "Gerar":

<figure><img src="/files/625f921b4358914139041d06486ae8d2e737c648" alt=""><figcaption></figcaption></figure>

После чего нажмите "Готово" и ключ api добавится в раздел:

<figure><img src="/files/8203ce9be933f430491c35e0f852c76996a85d03" alt=""><figcaption></figcaption></figure>

Você pode adicionar quantas chaves de API forem necessárias, atribuindo permissões de acesso diferentes a cada uma.

<figure><img src="/files/f3e5bece0f04a2f03a64f519fa61296eeb0d1c7e" alt=""><figcaption></figcaption></figure>

Em seguida, você precisa definir uma chave primária do projeto. Isso permite usar a chave em uma URL de solicitação com o placeholder #{api\_key}.

Para fazer isso, clique no botão "{+}" à direita da chave de API desejada:

<figure><img src="/files/3f88125f68f2289496041a2ccbdb61f7bc9f559e" alt=""><figcaption></figcaption></figure>

Em seguida, aparecerá um rótulo ao lado da chave, indicando que ela é a chave primária do projeto.

<figure><img src="/files/ec4d6776f41ad8774bbd1d92ca47add1f97691b5" alt=""><figcaption></figcaption></figure>

Você pode acessar a chave primária do projeto via api\_key: basta gerar a chave necessária, definir suas permissões e designá-la como a chave primária do projeto. Depois, na Calculadora, use a URL da solicitação com o placeholder #{api\_key}, que conterá o valor da chave primária do projeto.

<figure><img src="/files/fc68eeee3660d2775427a14838c0613343e990c1" alt=""><figcaption><p>URL da solicitação</p></figcaption></figure>

<figure><img src="/files/bad4d0260b76190dbab99a27d6d085a72b24cc1d" alt=""><figcaption></figcaption></figure>

Quaisquer outras chaves geradas com configurações de acesso serão consideradas chaves secundárias. Na URL da solicitação, você pode usar o valor delas em vez de #{api\_key}. Para fazer isso, copie o valor da chave secundária:

<figure><img src="/files/4e4d6e3a275f7750746f3c95c0ec937c06da611d" alt=""><figcaption></figcaption></figure>

e cole-o na URL da solicitação no lugar de #{api\_key}:

<figure><img src="/files/3d6e542cd755612435d265b35d64cf43ef987002" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Uma chave de API gerada usando o método antigo é definida como a chave primária do projeto por padrão e tem permissões completas.
{% endhint %}

{% hint style="danger" %}
Atenção!&#x20;

Se você excluir a chave definida como a chave primária do projeto, será necessário designar manualmente uma nova chave como primária.
{% endhint %}

{% hint style="success" %}
Por favor, observe!&#x20;

Se você tiver chaves de API geradas usando o método antigo, elas continuarão funcionando normalmente. Não é possível gerar novas chaves de API do tipo antigo.
{% endhint %}

## Como receber mensagens na URL de Webhook especificada nas configurações do projeto

![Configurações do projeto](/files/7a481645f0ca8bc11d1fd277552a0d23c3d079fa)

Cada mensagem recebida ou enviada será enviada como a seguinte solicitação JSON POST:

```
{
    "id": "ID da mensagem no sistema",
    "client": {
        "id": "ID do cliente no sistema",
        "recepient": "ID do cliente no mensageiro",
        "client_type": "tipo de mensageiro",
        "name": "nome do cliente",
        "avatar": "avatar do cliente",
        "created_at": "data de criação do cliente",
        "tag": "chave de assinatura",
        "group": "bot ao qual o cliente está vinculado"
    },
    "message": "texto da mensagem",
    "attachments": "array contendo links de arquivos ou dicionários de links de arquivos",
    "message_id": "ID do bloco de onde a mensagem foi enviada",
    "project_id": "ID do projeto",
    "is_input": "1 se a mensagem for do cliente, 0 se for do bot",
    "delivered": "1 se a mensagem foi enviada com sucesso, 0 se houve um erro",
    "error_message": "texto do erro de entrega da mensagem"
}
```

Se uma solicitação retornar um erro, ela não será repetida. Mesmo que o servidor retorne erros, as notificações continuarão sendo enviadas.

### Como criar uma solicitação JSON

Acesse as configurações do bloco onde os dados serão gravados na tabela.&#x20;

<figure><img src="/files/f256ec6e2a9ecbb26792e739205cebc50555e58b" alt=""><figcaption></figcaption></figure>

1. Adicione uma seção de Solicitação de API.
2. Selecione POST-JSON como tipo de solicitação.
3. Depois, preencha os campos da solicitação:

<figure><img src="/files/642cb6392a2e7bbd09b917934dacee4b88af8da5" alt=""><figcaption></figcaption></figure>

**URL da solicitação** — o caminho para a função que será chamada. Na documentação, isso sempre é mostrado na primeira linha ao lado do tipo de solicitação:

<figure><img src="/files/f598da4606861cc041eb9aa9c4caee1c5dc1649d" alt=""><figcaption></figcaption></figure>

**Valores salvos** — uma lista de parâmetros de resposta com os nomes das variáveis onde os resultados devem ser armazenados, no seguinte formato:

> **request\_parameter -> your\_variable**
>
> Se a resposta contiver parâmetros com uma estrutura complexa, processe-os da seguinte forma:
>
> * > "cell\_number":{"row":4,"col":2}\
>   > \
>   > \
>   > cell\_number|row ->String; \
>   > cell\_number|col -> Column<br>

**Cabeçalhos da solicitação** — preencha se necessário. Normalmente isso inclui o formato dos dados e/ou o token de acesso.

**Parâmetros JSON** — o corpo da solicitação, onde você especifica os parâmetros de dados em formato JSON. Exemplo:

**{"client\_id": "#{recipient\_id\_in\_builder}", "message":"Olá!"}**

Para entender a estrutura da resposta, escreva #{custom\_answer} no campo Mensagem para exibir o valor da variável.<br>

<figure><img src="/files/8a03f04ddff0bee1633524d33ed36b5f54f8e718" alt=""><figcaption><p>Recebendo o resultado de uma solicitação de API como mensagem</p></figcaption></figure>

Em seguida, a documentação lista os parâmetros permitidos na seção "Body":&#x20;

<figure><img src="/files/d5cf3cb5e8aafbce5a79bb98368d83beaac3fea5" alt="" width="551"><figcaption></figcaption></figure>

## Como usar um webhook universal

Os métodos listados agora podem ser executados como solicitações POST ou GET.

* [callback](#zapusk-bota)
* [whatsapp\_callback](#zapusk-bota)
* [message](#otpravka-soobshenii)
* [whatsapp\_message](#otpravka-soobshenii)

Anteriormente, nossos métodos tinham parâmetros fixos (como **client\_id** e **fb\_id**) para acionar ações do assinante, o que impunha certas limitações ao integrar com serviços de terceiros.

Agora você pode especificar qual parâmetro da solicitação o SaleBot deve usar para encontrar o ID do usuário. Use um parâmetro com o prefixo **value\_**, por exemplo, **value\_user\_id** ou **value\_group\_id**.

Além disso, o método de envio callback agora também pode ser acionado usando o e-mail do cliente (**client\_email**) ou número de telefone (**client\_phone**).

{% hint style="success" %}
O **callback**, **fb\_callback**, e **whatsapp\_callback** os métodos não estão vinculados a nomes de parâmetros específicos. Você pode especificar qual parâmetro contém o número de telefone, o e-mail ou o ID do cliente.
{% endhint %}

Isso é útil ao configurar o recebimento de webhook de um site.

**Para especificar qual variável contém o client\_id**, use o parâmetro value\_client\_id e informe o nome do parâmetro que contém esse valor.

**Para especificar qual variável contém o número de telefone**, use value\_phone.

**Para especificar qual variável contém o e-mail,** use value\_email.

**Para especificar qual variável contém o user\_id**, use value\_user\_id.

**Para especificar qual variável contém o group\_id**, use value\_group\_id.

**Para especificar a variável que contém a própria mensagem no webhook**, use value\_message (passado da mesma forma que os outros parâmetros).

Exemplo:

No endereço, especifique value\_client\_id = my\_client.

`https://chatter.mavibot.ai/api/d3f31dabef80ddeb73d43938b4ef8bb0/callback?value_client_id=my_client`\
`{"my_client":49177759, "message":"Olá mundo"}`

A solicitação será equivalente à abaixo:

`https://chatter.mavibot.pro/api/d3f31dabef80ddeb73d43938b4ef8bb0/callback`\
`{"client_id":49177759, "message":"Olá mundo"}`

Como você pode ver, o nome do parâmetro que contém o valor é precedido por **value\_**.

{% hint style="warning" %}
Por favor, observe!&#x20;

Alguns eventos geram notificações do sistema dentro do projeto.

Por exemplo, há notificações do sistema com um campo de mensagem que não está vazio, mas não contém texto do cliente.

Ao mesmo tempo, o projeto também pode gerar hooks de mensagens com conteúdo específico, como "message: new\_chat\_member".

Portanto, é importante verificar o conteúdo: ele será uma notificação do sistema ou um hook para um evento específico.
{% endhint %}

## Como iniciar o bot

### Iniciar o bot

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/callback</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/#{api\\_key}/callback><br>

Este método pode ser usado para acionar um funil para um cliente ou confirmar uma ação em um recurso externo. O cliente não verá esta mensagem.<br>

**Observe: quaisquer parâmetros que você enviar adicionalmente serão salvos na variável**

O método callback agora também pode ser acionado usando o e-mail do cliente (client\_email) ou número de telefone (client\_phone).

Permissão de acesso ao gerar uma chave: **"Permissão para modificar/excluir informações do cliente"**.

<img src="/files/a1ac22e7d4c418286ca9df6e36853405402df6af" alt="" data-size="original">

Caminho

chave api\* - token de acesso

Body

client\_phone - número de telefone usado para localizar o cliente

client\_email - e-mail usado para localizar o cliente

client\_id - ID do cliente no construtor

message - texto da mensagem

resume\_bot - True (parâmetro opcional). Se o bot estiver pausado, isso é usado para retomá-lo.&#x20;

Exemplo: resume\_bot = True

time\_shift - número. Se especificado, a mensagem será enviada após o número informado de segundos a partir do momento atual.

send\_time - data e hora no formato "%Y-%m-%d %H:%M:%S" (por exemplo, "2024-10-16 13:15:59"). Isso define a data e a hora para o envio da mensagem. Se time\_shift e send\_time forem especificados, time\_shift terá prioridade.

```
import requests
import json

params = {"message": "some_text", "client_id": "25554"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.salebot.pro/api/{token}/callback'
requests.post(url, json=params)
```

</details>

### Iniciando o bot usando um número do WhatsApp

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/whatsapp_callback</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/\\>\<api\_key>/whatsapp\_callback

Este método pode acionar o bot do WhatsApp depois que um cliente se registra no site ou envia uma solicitação com o número de telefone.

**Observe: quaisquer parâmetros que você enviar adicionalmente serão salvos na variável**

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/a1ac22e7d4c418286ca9df6e36853405402df6af" alt="" data-size="original">

Caminho

chave api\* - token de acesso

Body

name - nome do cliente\
message - texto da mensagem\
phone - número de telefone do cliente\
bot\_id - ID do bot\
resume\_bot - True (parâmetro opcional). Se o bot estiver pausado, use isso para retomá-lo. Exemplo: resume\_bot = True

time\_shift - número. Se especificado, a mensagem será enviada após o número informado de segundos a partir do momento atual.

send\_time - data e hora no formato "%Y-%m-%d %H:%M:%S" (por exemplo, "2024-10-16 13:15:59"). Isso define a data e a hora para o envio da mensagem. Se time\_shift e send\_time forem especificados, time\_shift terá prioridade.

</details>

### Iniciando o bot usando um ID do Telegram

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.pro/api/#{api_key}/tg_callback</summary>

URL da solicitação: <https://chatter.mavibot.pro/api/#{api\\_key}/tg\\_callback>

Este método pode ser usado para acionar um funil para um cliente ou confirmar uma ação em um site externo. O cliente não verá esta mensagem.

**Observe: quaisquer parâmetros que você enviar adicionalmente serão salvos nas variáveis.**

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/a1ac22e7d4c418286ca9df6e36853405402df6af" alt="" data-size="original">

Caminho

chave api\* - token de acesso

Body

message - texto da mensagem\
user\_id - ID do usuário no Telegram\
group\_id - nome do bot (terminado em bot)\
resume\_bot - True (parâmetro opcional). Se o bot estiver pausado, use isso para retomá-lo. Exemplo: resume\_bot = True

time\_shift - número. Se especificado, a mensagem será enviada após o número informado de segundos a partir do momento atual.

send\_time - data e hora no formato "%Y-%m-%d %H:%M:%S" (por exemplo, "2024-10-16 13:15:59"). Isso define a data e a hora para o envio da mensagem. Se time\_shift e send\_time forem especificados, time\_shift terá prioridade.

</details>

### Enviando mensagens callback para uma lista de clientes por platform\_id

<details>

<summary><mark style="color:verde;">POST</mark>  https://chatter.mavibot.ai/api/#{api_key}/send_callback_by_platform_id</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/#{api\\_key}/send\\_callback\\_by\\_platform\\_id>

Quando clientes com um platform\_id da lista forem encontrados no projeto, um callback será enviado com o texto do campo callback\_text.\
\ <mark style="color:vermelho;">**Limite: 1 solicitação = no máximo 300 envios**</mark>&#x20;

Exemplo de parâmetros da solicitação:\
{"platform\_ids":\[407184121, "79609879898", "2rwewefw"], "callback\_text": "test\_callback"}

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/a1ac22e7d4c418286ca9df6e36853405402df6af" alt="" data-size="original">

Caminho

chave api\* - token de acesso

Body

platform\_ids - Lista de IDs de clientes no mensageiro\
callback\_text - texto do callback\
group\_id - ID do bot

time\_shift - número. Se especificado, a mensagem será enviada após o número informado de segundos a partir do momento atual.

send\_time - data e hora no formato "%Y-%m-%d %H:%M:%S" (por exemplo, "2024-10-16 13:15:59"). Isso define a data e a hora para o envio da mensagem. Se time\_shift e send\_time forem especificados, time\_shift terá prioridade.

</details>

### Enviando uma mensagem callback para um cliente por e-mail

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/email_callback</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/#{api\\_key}/email\\_callback>

Este método pode acionar o bot de e-mail depois que um cliente se registra no site ou envia uma solicitação com o e-mail dele. O método localizará o e-mail do cliente ou o criará se não for encontrado.

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/a1ac22e7d4c418286ca9df6e36853405402df6af" alt="" data-size="original">

**Observe: quaisquer parâmetros que você enviar adicionalmente serão salvos na variável**

Caminho

chave api\* - token de acesso

Body

name - nome do cliente\
message - texto da mensagem\
email - endereço de e-mail\
email\_id\_bot - endereço de e-mail do bot\
resume\_bot - True (parâmetro opcional).&#x20;

Se o bot estiver pausado, use isso para retomá-lo. Exemplo: resume\_bot = True

time\_shift - número. Se especificado, a mensagem será enviada após o número informado de segundos a partir do momento atual.

send\_time - data e hora no formato "%Y-%m-%d %H:%M:%S" (por exemplo, "2024-10-16 13:15:59"). Isso define a data e a hora para o envio da mensagem. Se time\_shift e send\_time forem especificados, time\_shift terá prioridade.

</details>

## Como trabalhar com mensagens

### Parâmetros de envio de mensagem

**attachment\_type** — pode ser: **imagem, vídeo, link, arquivo ou áudio**.
\
Ao enviar um anexo, o parâmetro message é opcional.

**buttons** — define os botões a serem anexados à mensagem. O formato dos botões corresponde às configurações avançadas de botões.

Os botões podem ser passados de duas formas: com uma dica para mensageiros que não suportam botões, ou sem ela.

Exemplo do parâmetro buttons:

```
"buttons": {
  "hint": "Este texto será exibido no WhatsApp",
  "buttons": [
    {
      "type": "reply",
      "text": "Me fale sobre os serviços",
      "line": 0,
      "index_in_line": 0
    },
    {
      "type": "reply",
      "text": "Preços dos serviços",
      "line": 0,
      "index_in_line": 1
    },
    {
      "type": "reply",
      "text": "Contatos",
      "line": 1,
      "index_in_line": 0
    },
    {
      "type": "reply",
      "text": "Enviar uma solicitação",
      "line": 1,
      "index_in_line": 1
    }
  ]
}
```

### Enviando uma mensagem para um cliente

<details>

<summary><mark style="color:verde;">POST</mark>  https://chatter.mavibot.ai/api/#{api_key}/message</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/#{api\\_key}/message>

Este método pode ser usado para enviar mensagens de notificação. O parâmetro message é obrigatório, a menos que você esteja enviando um arquivo. Se você estiver enviando um arquivo, o texto é opcional.

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/a1ac22e7d4c418286ca9df6e36853405402df6af" alt="" data-size="original">

Caminho

chave api\* - token de acesso

Body

message\_id - número do bloco para envio\
message - texto da mensagem\
client\_id - ID do cliente no construtor\
attachment\_type - tipo de exibição do arquivo. Obrigatório se attachment\_url for fornecido.\
attachment\_url - URL do arquivo\
buttons - botões

time\_shift - número. Se especificado, a mensagem será enviada após o número informado de segundos a partir do momento atual.

send\_time - data e hora no formato "%Y-%m-%d %H:%M:%S" (por exemplo, "2024-10-16 13:15:59"). Isso define a data e a hora para o envio da mensagem. Se time\_shift e send\_time forem especificados, time\_shift terá prioridade.

```
import requests
import json

# Enviando uma mensagem de texto
params = {"message": "some_text", "client_id": "25554"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/message'
requests.post(url, json=params)

# Enviando um anexo
params = {
    "message": "some message",
    "client_id": "1234565",
    "attachment_type": "video/image/file",
    "attachment_url": "https://qwreqw"
}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/message'
requests.post(url, json=params)

# Em 'attachment_type', especifique 'video', 'image' ou 'file'
# dependendo do tipo de anexo: vídeo, imagem ou documento.
```

</details>

### Enviando uma mensagem no WhatsApp

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.salebot.pro/api/&#x3C;api_key>/whatsapp_message</summary>

URL da solicitação: <https://chatter.mavibot.pro/api/\\>\<api\_key>/whatsapp\_message

Permite enviar uma mensagem em nome do bot conectado para o número especificado. O whatsapp\_bot\_id deve ser obtido na seção "Mensageiros e chats". Cada conta do WhatsApp conectada recebe um identificador exclusivo do construtor.

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/a1ac22e7d4c418286ca9df6e36853405402df6af" alt="" data-size="original">

Caminho

chave api\* - token de acesso

Body

message\_id - número do bloco para envio\
whatsapp\_bot\_id - ID do bot do WhatsApp de onde a mensagem deve ser enviada\
attachment\_url - URL do arquivo\
attachment\_type - tipo de exibição do arquivo. Obrigatório se attachment\_url for fornecido.\
message - texto da mensagem\
phone - número de telefone do destinatário

time\_shift - número. Se especificado, a mensagem será enviada após o número informado de segundos a partir do momento atual.

send\_time - data e hora no formato "%Y-%m-%d %H:%M:%S" (por exemplo, "2024-10-16 13:15:59"). Isso define a data e a hora para o envio da mensagem. Se time\_shift e send\_time forem especificados, time\_shift terá prioridade.

```
import requests
import json

params = {"message": "some_text", "phone": "79875146788"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/whatsapp_message'
requests.post(url, json=params)
```

</details>

### Envio em massa de mensagens

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/broadcast</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/#{api\\_key}/broadcast>

Este método permite iniciar uma transmissão.

Você pode usar <mark style="color:vermelho;">**uma das seguintes opções mutuamente exclusivas**</mark>:

1. parâmetro list — a transmissão será enviada para a lista especificada de clientes.
2. parâmetro clients — a transmissão será enviada para uma matriz de IDs de clientes.
3. parâmetros platform\_ids e group\_id — a transmissão será enviada para uma matriz de platform\_ids (IDs de mensageiros) para o bot especificado (group\_id).
4. Se nenhum dos parâmetros acima for fornecido, a transmissão não será enviada.

Parâmetros obrigatórios: message (e/ou attachment\_type e attachment\_url) ou message\_id.

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/a1ac22e7d4c418286ca9df6e36853405402df6af" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

**list** - número da lista para a qual a transmissão deve ser enviada

clients - IDs de clientes no construtor

message - texto da mensagem

platform\_ids - IDs dos destinatários no mensageiro. Deve ser usado junto com o parâmetro obrigatório group\_id

group\_id - obrigatório apenas ao usar platform\_ids. Ignorado com outras opções. Especifica o bot para envio aos platform\_ids informados

attachment\_url - URL do arquivo

attachment\_type - tipo de exibição do arquivo. Obrigatório se attachment\_url for fornecido.

buttons - botões

message\_id - número do bloco para envio

shift — número de segundos entre mensagens. O padrão é 0.2.

time\_shift - número. Se especificado, a mensagem será enviada após o número informado de segundos a partir do momento atual.

send\_time - data e hora no formato "%Y-%m-%d %H:%M:%S" (por exemplo, "2024-10-16 13:15:59"). Isso define a data e a hora para o envio da mensagem. Se time\_shift e send\_time forem especificados, time\_shift terá prioridade.

```
import requests
import json

params = {"message": "some_text", "clients": ["5", "58", "110"]}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/broadcast'
requests.post(url, json=params)
```

</details>

### Recuperando o histórico de mensagens

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_history?client_id=</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_history?client\\_id=>

O parâmetro client\_id pode ser obtido aqui. <mark style="color:vermelho;">**ссылка**</mark>

Permissão de acesso ao gerar a chave: **"Permissão para ler informações do cliente"**.

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

client\_id - ID do cliente

limit - número de itens na resposta. Padrão: 2000, máximo: 2000

start\_date - data inicial do período de seleção (obrigatório se stop\_date for especificado), formato: dd.mm.aaaa&#x20;

stop\_date - data final do período de seleção (obrigatório se start\_date for especificado), formato: dd.mm.aaaa

```
{
  "status": "success",
  "result": [
    {
      "id": 104500,
      "answered": true,
      "client_replica": false,
      "message_id": 390,
      "message_from_outside": 0,
      "created_at": 1587895014,
      "text": "Miau miau",
      "attachments": {
        
      },
      "delivered": true,
      "error_message": "true",
      "manager_id": 12486,
      "manager_email": "example@mail.com"
    },
  ]
}
```

</details>

### Limpar histórico de mensagens

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/clear_history?client_id=</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/#{api\\_key}/clear\\_history?client\\_id=>

Exclui o histórico do chat&#x20;

Permissão de acesso ao gerar uma chave: **"Permissão para modificar/excluir informações do cliente"**.

<img src="/files/a1ac22e7d4c418286ca9df6e36853405402df6af" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

client\_id - ID do cliente

```
import requests
import json


token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/clear_history?client_id=85856'
requests.get(url)
```

</details>

## Como atribuir clientes

### Atribuindo um cliente a um funcionário

<details>

<summary><mark style="color:verde;">POST</mark>  https://chatter.mavibot.ai/api/#{api_key}/assign_to_user</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/#{api\\_key}/assign\\_to\\_user>

Este método permite atribuir um cliente a um funcionário. O parâmetro email é opcional. Se nenhum e-mail for informado, o sistema atribuirá o cliente de acordo com seu algoritmo.

Permissão de acesso ao gerar uma chave: **"Permissão para modificar/excluir informações do cliente"**.

<img src="/files/a1ac22e7d4c418286ca9df6e36853405402df6af" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

client\_id - ID do cliente\
email - e-mail do funcionário (opcional)

```
import requests
import json

params = {"client_id":"#{client_id}","email":"xxxxx@mail.ru"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/broadcast'
requests.post(url, json=params)
```

</details>

### Importando clientes para o sistema

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/load_clients</summary>

URL da solicitação: <https://chatter.mavibot.pro/api/#{api\\_key}/load\\_clients>

Este método permite importar clientes para o sistema. Ao enviar clientes do WhatsApp, você pode informar o número em qualquer formato, com ou sem o final @s.whatsapp.net.

O ID do grupo (group\_id) pode ser obtido AQUI via /api/\<api\_key>/connected\_channels. (Se client\_type = 13 (telefonia), então group\_id é uma string vazia: ""). <mark style="color:vermelho;">**ссылка**</mark>

O tipo de mensageiro de onde o cliente veio (client\_type) pode ser encontrado AQUI. <mark style="color:vermelho;">**ссылка**</mark>

Exemplo: \[{"platform\_id":"79875555555","group\_id":34810,"client\_type":6}]

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/a1ac22e7d4c418286ca9df6e36853405402df6af" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

platform\_id - número de telefone\
group\_id - ID do grupo\
client\_type - o tipo de mensageiro de onde o cliente veio

```
import requests
import json
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/load_clients'
params = [{ "platform_id": 274827917, "group_id": 169166236, "client_type":0},
{"platform_id":"79538550785@s.whatsapp.net", "group_id": "1hwF7lwEjv4SKYIGFhQnBw==", "client_type": 6}]
requests.post(url, json=params)
# se bem-sucedida, a função retornará um ID e um status de adição para cada item
# exemplo de resposta
# {"status":"success","items":[{"platform_id":"700000000@s.whatsapp.net","group_id":"5kqchxwyvdvFZOsp80q2qw==","client_type":6,"status":"success","id":1469409}]}
```

</details>

### Adicionar clientes a uma lista

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/add_to_list</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/\\>\<api\_key>/add\_to\_list

Adiciona clientes a uma lista

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/a1ac22e7d4c418286ca9df6e36853405402df6af" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

list\_id - número da lista\
clients - array de IDs de clientes

Exemplo:\
Parâmetros JSON\
{"list\_id":1170282, "clients":\[411262772, 646410963]}

</details>

### Remover clientes de uma lista

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/remove_from_list</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/#{api\\_key}/remove\\_from\\_list>

Remove clientes de uma lista

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/a1ac22e7d4c418286ca9df6e36853405402df6af" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

list\_id - número da lista\
clients - array de números de clientes no construtor Mavibot (valores de client\_id)

</details>

### Recuperar lista de clientes

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/get_clients</summary>

**URL da solicitação:** <https://chatter.mavibot.a/aipi/\\>\<api\_key>/get\_clients

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

offset – Deslocamento a partir do primeiro elemento

limit – Número de itens na resposta / Padrão: 500, Máximo: 500

list – Número da lista

reverse – Indica ordenação reversa (do registro mais antigo para o mais recente). Esse parâmetro funciona somente se a lista não for especificada.

Retorna o status e uma matriz de itens.

```
{
"status":"success",
"clients":[{
    "id":44483,
    "platform_id":"146467928",
    "client_type":0,
    "name":null,
    "avatar":null,
    "message_id":null,
    "project_id":1,
    "created_at":1588248599,
    "updated_at":1588248599,
    "custom_answer":null,
    "tag":null,
    "group":"143414131",
    "operator_start_dialog":null
    }
]
}
```

</details>

### Recuperar a lista de assinantes do bot em qualquer mensageiro

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/subscribers</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/#{api\\_key}/subscribers>

Recupera as informações do cliente de um mensageiro selecionado.

*<mark style="color:vermelho;">Atenção!</mark>* Este método não retorna variáveis.

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

page
\
tag – Tag especificada na página de inscrição
\
group – ID do grupo VK ao qual o assinante está vinculado
\
date\_from – Inscrito após esta data (timestamp)
\
date\_to – Inscrito antes desta data (timestamp)
\
client\_type – ID do mensageiro para o qual recuperar a lista de assinantes. Se não for especificado, todos os clientes serão retornados

```
[  
  {
    "id": 44886,
    "tag": null,
    "created_at": 1609867984,
    "name": "John Smith",
    "vk_id": "146467928",
    "group": "155824294",
    "variables": null
  },
  {
    "id": 44889,
    "tag": null,
    "created_at": 1609867984,
    "name": "Anna Smith",
    "vk_id": "1609867984",
    "group": "155824294",
    "variables": {
      "utm_source": "some_value"
    }
  }
]
```

</details>

## Como trabalhar com variáveis

### Atribuindo variáveis

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/save_variables</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/#{api\\_key}/save\\_variables>

&#x20;<mark style="color:verde;">**!**</mark>**&#x20;**<mark style="color:$success;">**Não há limite para esta solicitação.**</mark>&#x20;

Permite salvar variáveis tanto no lead quanto no cliente.
&#x20;Por padrão, a solicitação de atribuição de variáveis as adiciona às variáveis do negócio.
&#x20;Para atualizar variáveis no perfil do cliente, use o prefixo client. Por exemplo, para um telefone: client.phone.

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

**Atualizar**: O parâmetro clients permite atribuir variáveis em massa.
\
Exemplo: {"client\_id":49177759, "variables":{"client.phone":"88888888888"}}

**Caminho**

chave api\* - token de acesso

**Body**

clients – Array de IDs de clientes para atribuição de variáveis

client\_id – ID do cliente

variables – Hash de variáveis (pares chave-valor)

```
import requests
import json

params = {"client_id": "25554", "variables": {"var_name": "var_value"}}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/save_variables'
requests.post(url, json=params)
```

</details>

### Recuperar variáveis

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_variables?client_id=</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_variables?client\\_id=>

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

Exemplo: <https://chatter.mavibot.ai/api/d3f31dabef80ddeb73d43938b4ef8bb0/get\\_variables?client\\_id=49177759>

**Caminho**

chave api\* - token de acesso

**Body**

client\_id - ID do cliente

```
import requests
import json


token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/get_variables?client_id=85856'
requests.get(url)
```

</details>

## Como recuperar o ID do cliente (client\_id)

### Recuperar client\_id usando o valor platform\_id

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_platform_id</summary>

**URL da solicitação:** <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_client\\_id\\_by\\_platform\\_id>

Permissão de acesso ao gerar uma chave: **"Permissão para modificar ou excluir informações do cliente"**.

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

platform\_ids - array de IDs em um mensageiro\
group\_id - ID do bot

```
[{
"id":15099119,
"tag":null,
"created_at":1618815253,
"name":"ОЛЬГА БЕЛИК",
"avatar":"https:\\/\\/files.mavibot.ai\\/uploads\\/avatars\\/256865200.jpg",
"platform_id":"2568652",
"group":"Mavibotai_bot",
"variables":{"tg_username":"@belik"}},

{"id":21087377,
"tag":null,
"created_at":1626275893,
"name":"John Smith",
"avatar":"https:\\/\\/files.mavibot.ai\\/uploads\\/avatars\\/571830542.jpg",
"platform_id":"571830542",
"group":"Mavibotai_bot",
"variables":{"tg_username":"@jsmith61"}
}]
```

</details>

### Recuperar o ID do cliente do chat online

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/online_chat_client_id?recipient=</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/#{api\\_key}/online\\_chat\\_client\\_id?recipient=>

Este método permite integrar um site com um chatbot. Por exemplo, se um usuário visitar uma página promocional, você pode enviar imediatamente uma mensagem no chat com uma oferta personalizada.

Permissão de acesso ao gerar uma chave: "Permissão para modificar ou excluir informações do cliente".

<img src="/files/a1ac22e7d4c418286ca9df6e36853405402df6af" alt="" data-size="original">

**Caminho**

api key\* - token de acesso

**Body**

tag - tag (tag do cliente)\
name - nome do cliente\
recipient - ID do diálogo em um site

#### Onde obter o **recipient?**&#x20;

Você pode obtê-lo no site com o chat online da Mavibot.ai, use JS para obter a propriedade **MavibotAi.recipient\_id**.

<img src="/files/4996e29919f894fa88c82860159f0e702a07cc91" alt="" data-size="original">

```
{ "client_id": 36553 }
```

</details>

### Recuperar client\_id por número do WhatsApp

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/whatsapp_client_id?phone=</summary>

URL da solicitação: <https://chatter.mavibot.ai/api/#{api\\_key}/whatsapp\\_client\\_id?phone=>

Este método retorna o ID do cliente para fazer solicitações de API se você souber o número de WhatsApp do cliente.
\
Se não existir nenhum cliente com esse número, o método retornará um erro 404.

Permissão de acesso ao gerar uma chave: "Permissão para modificar ou excluir informações do cliente".

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

phone - número de telefone\
group\_id - ID do bot

</details>

### Recuperar client\_id por número de telefone

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/find_client_id_by_phone?phone= </summary>

URL da solicitação: <https://chatter.mavibot.ai/api/\\>\<api\_key>/find\_client\_id\_by\_phone?phone=&#x20;

Este método retorna o ID do cliente para fazer solicitações de API.

A busca é realizada tanto entre clientes do WhatsApp quanto por meio de variáveis.

Permissão de acesso ao gerar uma chave: "Permissão para modificar ou excluir informações do cliente".

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

phone - número de telefone

</details>

### Recuperar client\_id por e-mail

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_email?email= </summary>

URL da requisição: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_client\\_id\\_by\\_email?email=&#x20>;

Este método retorna o ID do cliente para fazer solicitações à API.
\
A busca é realizada usando variáveis.

Permissão de acesso ao gerar uma chave: "Permissão para modificar ou excluir informações do cliente".

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

email - e-mail para busca

</details>

### Recuperar client\_id por valor de variável

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_var?var=&#x26;val=</summary>

URL da requisição: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_client\\_id\\_by\\_var?var=\\&val=>

Este método retorna o ID do cliente para fazer solicitações de API.

Permissão de acesso ao gerar a chave: "Permissão para ler informações do cliente"

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

**var -** nome da variável para buscar\
**val -** valor da variável\
**group\_id -** ID do grupo\
**search\_in -** passe o valor 'order' para pesquisar nas variáveis de negócio; pesquisa até três variáveis para clientes de projetos e retorna uma lista de clientes que possuem todas as variáveis especificadas.

</details>

### Recuperar o ID do cliente criado mais recentemente por valor de variável

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_latest_client_id_by_var?var=&#x26;val=</summary>

URL da requisição: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_latest\\_client\\_id\\_by\\_var> ?var=\&val=

Este método retorna o ID do cliente criado mais recentemente para fazer solicitações à API. Ele pesquisa tanto variáveis de cliente quanto de negócio.

Permissão de acesso ao gerar a chave: "Permissão para ler informações do cliente"

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

**var -** nome da variável para buscar\
**val -** valor da variável

</details>

### Recuperar uma lista de valores de client\_id por valor de variável

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_all_client_id_by_var?var=&#x26;val=</summary>

URL da requisição: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_all\\_client\\_id\\_by\\_var?var=\\&val=>

Este método retorna uma lista de IDs de clientes que possuem a variável especificada com o valor especificado.

Permissão de acesso ao gerar a chave: "Permissão para ler informações do cliente"

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

**var -** nome da variável para buscar\
**val -** valor da variável

```
{
    // Resposta
}
```

</details>

### Recuperar uma lista de valores de client\_id com base em vários valores de variáveis

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_all_client_id_by_several_vars?var=val</summary>

URL da requisição: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_all\\_client\\_id\\_by\\_several\\_vars?var=val>

Permissão de acesso ao gerar a chave: "Permissão para ler informações do cliente".

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

**Caminho**

api key\* - token de acesso

**Body**

variável1 - Valor1

variável2 - Valor2

variável3 - Valor3

```
{
 "status":"success","client_ids":[93891114]
}
```

</details>

### Buscar por variáveis

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/find_clients</summary>

URL da requisição: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_clients>

Este método pesquisa por variáveis e retorna uma lista de IDs de clientes que atendem às condições da consulta.

Por padrão, a busca é realizada nas variáveis do cliente (recomendado): {"q": {"result": "ok", "var": "home", "var": "60"}} – o cliente deve ter todas as variáveis especificadas

Buscar nas variáveis de negócio; pelo menos uma das variáveis especificadas deve estar presente: {"q": {"result": "ok", "var": "home", "var": "60"}, "search\_in": "order", "include\_all": False}

O nome da variável do cliente é igual a um dos valores da lista: {"q": {"name": {"\_in": \["Joe", "Jane", "Donald"]}}}

O nome da variável do cliente NÃO é igual a nenhum dos valores da lista: {"q": {"name": {"\_not\_in": \["Joe", "Jane", "Donald"]}}}

O nome da variável do cliente não é igual a "Joe": {"q": {"name": {"\_not": "Joe"}}}

**Observação: a comparação numérica funciona somente se todos os clientes tiverem valores numéricos na variável pesquisada. Se até mesmo um cliente tiver uma string, a solicitação falhará.**

Permissão de acesso ao gerar a chave: "Permissão para ler informações do cliente"

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

Parâmetros

**Caminho**

chave api\* - token de acesso

**Body**

q – parâmetro obrigatório, contém as condições da consulta para pesquisa de variáveis

search\_in – especifica as variáveis de qual entidade devem ser pesquisadas; se não for fornecido, a busca será feita nas variáveis do cliente. Pode receber o valor order.

include\_all – indica se todas as condições em q devem ser atendidas;

False – se pelo menos uma condição corresponder, a entidade será selecionada

```
Sucesso
{"status":"success","client_ids":[41203, 5622354, 785212]} 
{"status":"success","client_ids":[]} 
{"status": "fail", "message": "Parameter \"q\" required"} {"status": "fail", "message": "Error in parameter format"}
Erro
{"status":"fail","message":"Something went wrong"}
```

</details>

## Como trabalhar com negócios

### Recuperar o ID do negócio atual

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_current_order_id</summary>

**URL da solicitação:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_current\\_order\\_id>

Permissão de acesso ao gerar a chave: "Permissão para ler informações do CRM".

<img src="/files/ee55e3c6d68f143ce70c1bc411fd7b8dda03c362" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

client\_id - ID do cliente

```
Resposta bem-sucedida: {"status":"success","order_id":40632}, onde
order_id - ID do negócio atual
Resposta de erro: {"status":"client_not_found"}
```

</details>

### Recuperar a lista de negócios

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_orders</summary>

**URL da solicitação:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_orders>

Permissão de acesso ao gerar a chave: "Permissão para ler informações do CRM"

<img src="/files/ee55e3c6d68f143ce70c1bc411fd7b8dda03c362" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

client\_id - ID do cliente

**order\_status** - etapa do negócio: \
0 - negócios ativos\
1 - negócios bem-sucedidos\
2 - negócios malsucedidos

```
Resposta bem-sucedida: {"status":"success","order_id":[40338,40340,40341]} 
Resposta de erro: {"status":"client_not_found"}
```

</details>

### Mover um negócio para a próxima etapa no funil da Mavibot

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/move_order_to_next_state</summary>

**URL da solicitação:** <https://chatter.mavibot.ai/api/#{api\\_key}/move\\_order\\_to\\_next\\_state>

Permissão de acesso ao gerar a chave: "Permissão para modificar/excluir informações do CRM"

<img src="/files/2b0442fecf2d98fd9532f5d0c085f697e7e6c067" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

client\_id - ID do cliente

**order\_id** - ID do negócio

```
Resposta bem-sucedida: 
{"status":"success","state_id":37}, где 
state_id - ID da etapa no MavibotCRM 
Resposta de erro: 
{"status":"client_not_found"}
```

</details>

### Recuperar dados do negócio

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/get_order_vars</summary>

**URL da solicitação:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_order\\_vars>

Permissão de acesso ao gerar a chave: "Permissão para ler informações do CRM"

<img src="/files/ee55e3c6d68f143ce70c1bc411fd7b8dda03c362" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

client\_id - ID do cliente

**order\_id** - ID do negócio

variables - matriz de variáveis\
(formato:\["var\_name1", "var\_name2"])

```
Resposta bem-sucedida: 
{"status":"success","result":{"var_name1":"111","var_name2":"13.04.2023"}} 

Exemplo de erro: 
{"status":"client_not_found"}
```

</details>

### Adicionar variáveis do negócio

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/set_order_vars</summary>

**URL da solicitação:** <https://chatter.mavibot.ai/api/#{api\\_key}/set\\_order\\_vars>

Permissão de acesso ao gerar a chave: "Permissão para modificar/excluir informações do CRM"

<img src="/files/2b0442fecf2d98fd9532f5d0c085f697e7e6c067" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

client\_id - ID do cliente

**order\_id** - ID do negócio

variables - um dicionário de variáveis (a chave é o nome da variável, e o valor é o que deve ser salvo nessa variável)\
(formato:{"var\_name": "var\_velue"})

```
Resposta bem-sucedida: {"status":"success"} 
Resposta de erro: {"status":"order 12345 not found"}
```

</details>

### Criar um negócio

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/create_order</summary>

**URL da solicitação:** <https://chatter.mavibot.ai/api/#{api\\_key}/create\\_order>

Permissão de acesso ao gerar a chave: "Permissão para modificar/excluir informações do CRM"

<img src="/files/2b0442fecf2d98fd9532f5d0c085f697e7e6c067" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

client\_id - ID do cliente

name - nome do negócio

description - descrição do negócio

budget - valor do negócio

Você deve especificar um dos seguintes parâmetros na requisição: client\_id, email ou phone.
\
Se vários parâmetros forem fornecidos, apenas um será usado. A ordem de prioridade é: client\_id > phone > email.
\
Se phone ou email for fornecido e não existir um cliente com esse número de telefone ou e-mail, um novo cliente será criado.

```
Resposta bem-sucedida: {"status":"success","order_id":40654}, 
onde order_id é o ID do novo negócio ativo.
Resposta de erro: {"status":"client_not_found"}
```

</details>

### Mover um negócio para uma etapa no MavibotCRM

<details>

<summary><mark style="color:verde;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/set_order_state</summary>

**URL da solicitação:** <https://chatter.mavibot.ai/api/#{api\\_key}/set\\_order\\_state>

Permissão de acesso ao gerar a chave: "Permissão para modificar/excluir informações do CRM"

<img src="/files/2b0442fecf2d98fd9532f5d0c085f697e7e6c067" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

client\_id - ID do cliente

state\_id - o número da etapa para a qual o negócio do cliente deve ser movido

</details>

### Recuperar o ID da etapa do funil no Mavibot CRM

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_order_state</summary>

**URL da solicitação:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_order\\_state>

Permissão de acesso ao gerar a chave: "Permissão para ler informações do CRM"

<img src="/files/ee55e3c6d68f143ce70c1bc411fd7b8dda03c362" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

**Body**

client\_id - ID do cliente

state\_id - ID do negócio (se não for especificado, o método retornará o ID da etapa do negócio atual)

```
Exemplo de resposta bem-sucedida:
{'status': 'success', 'state_id': 123456}

Exemplo de resposta malsucedida:
{'status': 'order not found'}
```

</details>

## Quais outras funcionalidades estão disponíveis?

### Verificar se um número de telefone tem WhatsApp

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/check_whatsapp</summary>

**URL da solicitação:** <https://chatter.mavibot.ai/api/#{api\\_key}/check\\_whatsapp>

**Para usar este método, o WhatsApp deve estar conectado ao Mavibot.**

Permissão de acesso ao gerar uma chave: "Permissão para modificar ou excluir informações do cliente".

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

Pode ser chamado usando GET ou POST.
\
O número de telefone pode ser fornecido em qualquer formato.

**Caminho**

chave api\* - token de acesso

**Body**

phone - número de telefone para verificar

</details>

### Obter a lista de mensageiros conectados ao projeto

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/connected_channels</summary>

URL da requisição: <https://chatter.mavibot.ai/api/\\>\<api\_key>/connected\_channels

Permissão de acesso ao gerar uma chave: "Permissão para modificar ou excluir informações do cliente".

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

A função retorna o parâmetro group\_id para cada mensageiro, que deve ser usado ao importar clientes.

Para o WhatsApp, também retorna um **status** campo, que pode ter os seguintes valores:<br>

**NOT\_STARTED = 0**\
**STARTED = 1**\
**ASLEEP = 2**\
**STOPPED = 3**

**Caminho**

chave api\* - token de acesso

```
{'project_id': 1, 
'viber': [{
        'id': 14, 
        'uri': 'mavibotstage', 
        'name': 'mavibotstage', 
        'enabled': true,
        'group_id': 11}], 
'facebook': [], 
'telegram': [{
        'id': 23, 
        'short_name': 'bulls_vs_bears_bot', 
        'name': 'bulls_vs_bears_bot', 
        'enabled': true,
        'group_id': 'bulls_vs_bears_bot'}], 
'whatsapp': [], 
'avito': [], 
'ok': [], 
'vkontakte': [{
        'id': 33, 
        'group': '143414131',
        'group_id': '143414131'}]
}
```

</details>

### Recuperar a lista de blocos do fluxo do bot

<details>

<summary><mark style="color:azul;">GET</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/get_messages</summary>

**URL da solicitação:** <https://chatter.mavibot.ai/api/\\>\<api\_key>/get\_messages

Permissão de acesso ao gerar uma chave: "Permissão para modificar ou excluir informações do cliente".

<img src="/files/cd7649e7bc068e93eac233a733b5a7fd7308eba8" alt="" data-size="original">

**Caminho**

chave api\* - token de acesso

</details>

### Recuperar dados aninhados do cliente

<details>

<summary>delimiter</summary>

Para recuperar client\_id e/ou o número de telefone do cliente a partir de dicionários aninhados (não no primeiro nível), use o parâmetro delimiter.

Adicione o seguinte à URL da sua requisição:

?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2}\&delimiter\_value\_phone={key1}1{key2}&#x20;

onde:

?delimiter=1 – o valor do delimitador que separa as chaves {key1}1{key2}1{key3}

delimiter\_value\_client\_id={key1}1{key2} – para recuperar o ID do cliente

delimiter\_value\_phone={key1}1{key2} – para recuperar o número de telefone do cliente

{key1}, {key2}, … – chaves que contêm os valores (podem incluir quaisquer caracteres, exceto o delimitador). Você pode ter uma quantidade ilimitada de chaves:\
?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2}1{key3}1{key4}1{key5}1{key6}. \
**As chaves são passadas sem chaves curvas.**

Use o delimitador entre as chaves. Por exemplo, se delimiter=2, então {key1}2{key2}2{key3}; se delimiter=5, então {key1}5{key2}5{key3}. Certifique-se de que a chave não contenha o caractere do delimitador.

Exemplo:

<https://chatter.mavibot.a/aipi/\\>\<api\_key>/callback<mark style="color:amarelo;">**?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2}\&delimiter\_value\_phone={key1}1{key2}**</mark>&#x20;

Você também pode recuperar apenas o ID ou apenas o número de telefone:&#x20;

<https://chatter.salebot.pro/api/\\>\<api\_key>/callback<mark style="color:verde;">**?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2} -**</mark> apenas o ID do cliente;

<https://chatter.salebot.pro/api/\\>\<api\_key>/callback<mark style="color:verde;">**?delimiter=1delimiter\_value\_phone={key1}1{key2}**</mark> - apenas o número de telefone;

Métodos da API:

1. Iniciar bot: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/callback
2. Iniciar bot pelo número do WhatsApp: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/whatsapp\_callback
3. Iniciar bot pelo ID do Telegram: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/tg\_callback
4. Enviar mensagem de callback para cliente por e-mail: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/email\_callback
5. Enviar mensagem para o cliente: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/message
6. Enviar mensagem do WhatsApp: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/whatsapp\_message
7. Envio em massa: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/broadcast
8. Atribuir variáveis: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/save\_variables
   \\

</details>

{% hint style="success" %}
Se você precisar de métodos adicionais, entre em contato com o suporte.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mavibot.ai/doc/pt/trabalhando-com-a-api/construtor-de-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.