Referência de SDK

Todo SDK do Telybot — Android, iOS, React Native, Flutter, Ionic — implementa o mesmo contrato pequeno. Se você usou um, usou todos.

A API

Abrir com uma pergunta. Passe uma pergunta para show e ela entra na caixa de mensagem do chat; o cliente lê e toca em enviar. Ela viaja no #fragment do link, então nunca chega a um log do servidor. Até 500 caracteres, em uma linha.

O chat dentro da sua própria tela. Android KeydaBotView, iOS KeydaBot.makeChatViewController ou SwiftUI KeydaBotView, React Native <KeydaBotChat />, Flutter KeydaBotChat, e o embedWidget() do pacote Ionic. Ele não tem botão de fechar — a navegação da sua tela é a saída. No Android, Voltar fecha primeiro um item ou carrinho aberto: React Native e Flutter fazem isso por você enquanto o chat é a tela da frente, e com a KeydaBotView nativa o seu tratamento de Voltar chama o goBack() dela.

Seu cliente logado. Dê ao SDK o nome, o número de telefone ou o e-mail do seu cliente e o chat preenche o que seu app já sabe. Os dados são oferecidos, nunca enviados: aparecem no formulário “falar com uma pessoa”, em um pedido, um agendamento e uma pergunta de boas-vindas que pede nome, telefone ou e-mail, e é o cliente quem os envia. Eles viajam no #fragment do link e são a palavra do seu app, não uma identidade verificada. Um valor que o chat recusaria é deixado de fora: um nome com mais de 80 caracteres, um número de telefone sem 8 a 15 dígitos, um endereço de e-mail sem um domínio válido. O chat em tela cheia do Ionic abre no navegador do sistema, que guarda endereços no histórico, por isso não os aceita; o widget incorporado dele aceita.

Uma resposta enquanto o chat está fechado. Quando um cliente pede para falar com uma pessoa e fecha o chat, sua resposta pelo painel fica esperando na conversa. Os SDKs para Android, iOS, React Native e Flutter verificam isso quando seu app volta ao primeiro plano e avisam seu app, para que você possa mostrar um ponto no botão do chat até o cliente abrir o chat. Eles só perguntam sobre chats em que o cliente pediu uma pessoa nos últimos 14 dias. Um chat que seu app mantém carregado fora de vista, como uma aba de Ajuda em segundo plano, não conta como lido: o ponto fica até o cliente olhar. Isto não é uma notificação push: a resposta é percebida quando o app é aberto.

De propósito, não há mais nada. Nenhuma API de envio de mensagens e nenhuma chamada de identidade do usuário — porque nenhuma das duas funciona de ponta a ponta ainda, e um método que não funciona é pior do que um que falta.

A URL que cada SDK abre

{baseUrl}/chat/{clientId}

baseUrl tem como padrão https://telybot.com e pode ser substituído em qualquer plataforma, seja para ambiente de testes (staging) ou instalação auto-hospedada.

Por que uma web view e quanto ela custa a você

Há uma única interface de chat, fornecida pela plataforma, e todas as superfícies a carregam.

O que você ganha: uma alteração feita pelo proprietário no painel — cor de destaque, mensagem de boas-vindas, nome do bot, ativação — chega a todos os aplicativos instantaneamente, sem necessidade de nova versão. Uma correção é aplicada em todos os lugares de uma só vez. O chat é idêntico em todas as plataformas.

Quanto custa: o chat precisa de uma conexão. Não há modo offline e ainda não há notificações push.

Preferimos que você saiba disso antes de publicar do que descubra depois.

Garantias que cada SDK oferece

1. Saídas de navegação. Um link para qualquer outra origem abre no navegador do sistema em vez de substituir o chat. Sem isso, um toque em um link derodapé encerra a conversa do cliente sem caminho de volta.
2. Continuidade da conversa. O armazenamento local (DOM storage) está ativado, então um cliente que fecha o app e volta encontra o histórico exatamente onde parou (por 24 horas).
3. O teclado nunca cobre o campo de entrada.
4. Áreas seguras são respeitadas — nenhum chat é desenhado sob um entalhe ou indicador de início.
5. Nenhuma falha chega ao seu aplicativo. Um carregamento com erro exibe a opção de tentar novamente.
6. Sem análises de dados, sem identificadores de dispositivo, sem dependências de terceiros. Adicionar um SDK da Telybot não adiciona nenhum rastreador ao seu aplicativo.
7. Voltar fecha primeiro o que o cliente está vendo. No Android, Voltar sobre um item, carrinho ou agendamento aberto fecha isso, e só depois o chat (SDK 0.2.0 e mais recentes).

Dentro do chat

Tudo isso vem da página hospedada, então chega a todos os apps sem atualizar o SDK:

• Uma mensagem de boas-vindas com botões de sugestão, no idioma configurado para o bot.
• A conversa fica no dispositivo por 24 horas, e o chat não cria nenhum id de visitante. Em um site, uma conversa dura uma aba do navegador. (O chat em tela cheia do SDK Ionic precisa da 0.2.0 para isso.)
• Pedidos e agendamentos, quando o negócio os aceita: um carrinho, datas e horários de agendamento, um link para ligar para o negócio quando um pedido ou agendamento esperou demais, e “Adicionar à agenda” para um agendamento confirmado.
• Anexos: fotos (JPEG, PNG, WebP, GIF) e arquivos PDF, DOCX, TXT, CSV e MD. Os SDKs Android e Flutter precisam da 0.1.4 ou mais recente para o botão de anexar, e o Flutter precisa da 0.2.0 para documentos.
• “Adicionar à agenda” é um link para um arquivo .ics. O iOS o abre no Calendário como um calendário para assinar. O Android oferece o app de agenda do telefone quando ele importa arquivos .ics — o Google Agenda atual faz isso — e, caso contrário, o navegador baixa o arquivo.

Formato do Client id

kb_live_ followed by 8-48 hexadecimal characters

Qualquer outra coisa é rejeitada na inicialização, em vez de abrir um erro 404 na frente de um cliente. O client id é público por design — fica visível em qualquer site que incorpore o widget — e não tem capacidade de ler ou alterar sua conta. Veja limites e segurança.

Origem

Público, com licença MIT: github.com/telybotai/telybot-Sdks. O contrato compartilhado que todos os pacotes seguem está em CONTRACT.md no topo desse repositório.