Integrar com outros aplicativos de mensagem pela API HTTP

O GG.chatbot traz integrações nativas para a web e o WhatsApp. Para plataformas sem integração dedicada — KakaoTalk, LINE, WeChat, Telegram, Viber ou qualquer aplicativo de conversa proprietário —, você ainda pode conduzir uma conversa chamando a API HTTP por conta própria.

A integração fica entre o aplicativo de mensagem e o GG.chatbot: recebe cada mensagem que chega da plataforma, encaminha ao GG.chatbot e devolve a resposta do bot ao usuário.

Como funciona

Para cada usuário, você precisa guardar um sessionId do GG.chatbot, para que a conversa mantenha o estado entre as mensagens.

Receber um webhook do aplicativo de mensagem

A maioria das plataformas (KakaoTalk, LINE, Telegram e outras) permite registrar uma URL de webhook, chamada sempre que alguém envia uma mensagem. Crie um endpoint HTTP no seu servidor para tratar essas chamadas.

Iniciar a conversa na primeira mensagem

Se você ainda não tem um sessionId para esse usuário, chame o endpoint de iniciar conversa:

curl -X POST https://ggchatbot.com/api/v1/typebots/<publicId>/startChat \
  -H "Content-Type: application/json" \
  -d '{}'

Guarde o sessionId devolvido junto ao ID do usuário na plataforma, no seu banco de dados.

Encaminhar as mensagens seguintes

A cada nova mensagem do mesmo usuário, chame o continueChat com a sessão guardada:

curl -X POST https://ggchatbot.com/api/v1/sessions/<sessionId>/continueChat \
  -H "Content-Type: application/json" \
  -d '{"message": "user reply here"}'

Exibir a resposta do bot no aplicativo de mensagem

Os dois endpoints devolvem um vetor messages descrevendo o que o bot quer dizer: balões de texto, imagens, botões e assim por diante. Converta cada mensagem no elemento equivalente da plataforma de destino — um balão de texto do KakaoTalk, uma mensagem de modelo do LINE ou um teclado embutido do Telegram, por exemplo.

Se a resposta contiver um input, apresente-o ao usuário: botões viram respostas rápidas, uma entrada de texto apenas aguarda a próxima mensagem, e assim por diante. Quando ele responder, volte ao passo anterior.

Pontos de atenção

Autenticação. Endpoints públicos (/api/v1/typebots/<publicId>/startChat) não exigem token. Se quiser usar o endpoint de pré-visualização ou qualquer rota autenticada, gere um token de API.
Duração da sessão. As sessões expiram após um período de inatividade. Trate os erros 404 do continueChat iniciando uma nova sessão de forma transparente.
Compatibilidade dos blocos. Blocos que dependem da incorporação web — interface de envio de arquivo, formulário de pagamento, vídeos incorporados — não têm equivalente direto na maioria dos aplicativos de mensagem. Ao mirar plataformas externas, mantenha o fluxo baseado em texto.
Limites de requisição. As plataformas de mensagem costumam impor limites rígidos. Enfileire as mensagens de saída quando o bot enviar vários balões seguidos.