52 · O seu próprio aplicativo¶

O seu bot pode trabalhar com um programa que você mesmo roda, neste computador ou na sua própria rede: um caixa, uma planilha de reservas, um script que você escreveu. O bot chama as ferramentas dele, o programa avisa o bot quando algo acontece, e uma conversa que o programa mantém com os seus clientes pode ser respondida pelo bot. Nada do que ele envia passa pela Stalwart: o programa e o bot conversam na sua máquina. Os seus próprios aplicativos estão nos planos pago e empresarial.

Idiomas

O seletor lê turnos escritos em inglês e em português do Brasil (pt-BR). O idioma é escolhido, nunca adivinhado a partir do turno: na página Settings do console (Language the selector reads), em language numa requisição de plano, ou no settings.language do seu arquivo de vocabulário; sem nenhum deles, inglês. Um turno em português pode ser digitado com os acentos ou sem eles. O português europeu não é uma gramática que o seletor tenha, e um turno em qualquer outra língua não é lido.

Escrevendo o aplicativo¶

stalwart_agents.local_app é o lado do aplicativo. Dê ao aplicativo o nome que o arquivo do bot dá a ele, dê a ele ferramentas, e rode-o:

from stalwart_agents.local_app import LocalApp, Refused

app = LocalApp("caixa")                    # o segredo é lido de STALWART_APP_SECRET

@app.tool
def estoque_de(item: str) -> dict:
    """Quantas unidades de um item restam."""
    return {"item": item, "restam": 12}

@app.on_send
def enviar(to: str, text: str, in_reply_to: str) -> None:
    meu_chat.enviar(to, text)              # levante Refused("por quê") para avisar o dono que não foi enviado

app.run()                                  # serve as ferramentas em http://127.0.0.1:8765/mcp

As suas ferramentas são as que @app.tool marca, cada uma lida das suas anotações de tipo e da sua docstring. Elas são servidas só neste computador; outra máquina da sua rede só as alcança se o aplicativo for criado com lan=True e o arquivo do bot disser lan: allow.
O que ele avisa o bot -- app.event("novo_pedido", {"order_id": "4411"}, id="pedido-4411") inicia a tarefa cujo gatilho nomeia esse evento; app.message("chat:+5511999990000", "tem leite de aveia?", id="m-1") é um turno da conversa dessa pessoa. Cada um é assinado com o segredo do aplicativo. Um id que o bot já viu não inicia nada, então o aplicativo pode enviar de novo o que não tem certeza de que chegou.
As respostas da sua conversa voltam pela função que @app.on_send nomeia, que o bot chama como a ferramenta send_message. Uma recusa que você levanta ali aparece no cartão do dono, com as suas palavras.

Contando ao bot sobre ele¶

O arquivo do bot nomeia cada aplicativo em own_apps (capítulo 48), com o seu endereço e, se ele mantém conversas, channel: true:

own_apps:
  caixa: {address: "http://127.0.0.1:8765/mcp", channel: true}
triggers:
  novo_pedido: {kind: webhook, app: caixa}
  conversa_caixa: {kind: message, in: custom, app: caixa}

As ferramentas dele entram no bot como as de qualquer servidor. O bot mantém cada uma sem classificação até você classificá-la, então toda escrita espera a sua aprovação.

O seu segredo¶

Na página de Aprovações do host, Seus próprios aplicativos lista cada aplicativo: onde o bot o alcança, onde chegam as suas conversas e se o seu segredo está definido. Criar o segredo cria um, guardado selado neste computador e mostrado a você uma única vez: coloque-o logo nas configurações do aplicativo (STALWART_APP_SECRET). Criar um novo faz o antigo deixar de funcionar. Um segredo que o arquivo do bot nomeia como ${ALGUMA_VARIAVEL} é seu para guardar onde você guarda, e a página não cria nenhum para ele.

O que ele não pode fazer¶

Um aplicativo é alcançado neste computador, ou na sua própria rede se você permitir; nunca num endereço da internet, que o bot recusa.
No plano gratuito, o bot recusa tudo o que um aplicativo envia a ele.
As ferramentas do aplicativo são verificadas como qualquer ferramenta, as suas descrições também; nada é confiável só porque roda na sua máquina.