Referência do SDK

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

A API

Abrir com uma pergunta. Passe uma pergunta a show e ela fica na caixa de mensagem do chat; o cliente lê-a e toca em enviar. Viaja no #fragment da ligação, por isso nunca chega a um registo do servidor. Até 500 caracteres, numa só linha.

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

O seu cliente com sessão iniciada. Dê ao SDK o nome, o número de telefone ou o e-mail do seu cliente e o chat preenche o que a sua aplicação já sabe. Os dados são oferecidos, nunca enviados: aparecem no formulário “falar com uma pessoa”, numa encomenda, numa marcação e numa pergunta de boas-vindas que pede nome, telefone ou e-mail, e é o cliente que os envia. Viajam no #fragment da ligação e são a palavra da sua aplicação, não uma identidade verificada. Um valor que o chat recusaria fica 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 ecrã inteiro do Ionic abre no navegador do sistema, que guarda endereços no histórico, por isso não os aceita; o widget incorporado aceita.

Uma resposta enquanto o chat está fechado. Quando um cliente pede para falar com uma pessoa e fecha o chat, a sua resposta a partir do painel fica à espera na conversa. Os SDKs para Android, iOS, React Native e Flutter verificam isso quando a sua aplicação volta ao primeiro plano e avisam a aplicação, para que possa mostrar um ponto no botão do chat até o cliente o abrir. Só perguntam pelos chats em que o cliente pediu uma pessoa nos últimos 14 dias. Um chat que a sua aplicação mantém carregado fora de vista, como um separador 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 é notada quando a aplicação é aberta.

Deliberadamente não há mais nada. Nenhuma API de envio de mensagens e nenhuma chamada de identidade do utilizador — porque nenhuma das duas funciona ainda de ponta a ponta, 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, para ambiente de homologação ou instalação auto-hospedada.

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

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

O que você recebe: 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 imediatamente, 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 lançar do que descubra depois.

Garantias que cada SDK oferece

1. Fugas 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 de rodapé encerra a conversa do cliente sem volta.
2. Continuidade da conversa. O armazenamento DOM está ativado, então um cliente que fecha o aplicativo e retorna encontra o histórico onde o deixou (por 24 horas).
3. O teclado nunca cobre o campo de entrada.
4. As áreas seguras são respeitadas — nenhum chat é exibido sob o entalhe da tela ou o indicador de início.
5. Nenhum erro afeta a sua aplicação. Um carregamento falhado mostra uma tentativa de repetição.
6. Sem análises, sem identificadores de dispositivos, sem dependências de terceiros. Adicionar um SDK da Telybot não adiciona nenhum localizador à sua aplicação.
7. Voltar fecha primeiro o que o cliente está a ver. No Android, Voltar sobre um item, carrinho ou marcação abertos fecha isso, e só depois o chat (SDK 0.2.0 e posteriores).

Dentro do chat

Tudo isto vem da página alojada, por isso chega a todas as aplicações sem atualizar o SDK:

• Uma mensagem de boas-vindas com botões de sugestão, no idioma definido para o bot.
• A conversa fica no dispositivo durante 24 horas, e o chat não cria nenhum id de visitante. Num site, uma conversa dura um separador do navegador. (O chat em ecrã inteiro do SDK Ionic precisa da 0.2.0 para isto.)
• Encomendas e marcações, quando o negócio as aceita: um carrinho, datas e horas de marcação, uma ligação para telefonar ao negócio quando uma encomenda ou marcação esperou demasiado, e “Adicionar ao calendário” para uma marcação confirmada.
• Anexos: fotografias (JPEG, PNG, WebP, GIF) e ficheiros PDF, DOCX, TXT, CSV e MD. Os SDKs Android e Flutter precisam da 0.1.4 ou posterior para o botão de anexar, e o Flutter precisa da 0.2.0 para documentos.
• “Adicionar ao calendário” é uma ligação para um ficheiro .ics. O iOS abre-o no Calendário como um calendário a subscrever. O Android propõe a aplicação de calendário do telemóvel quando esta importa ficheiros .ics — o Google Calendar atual fá-lo — e, caso contrário, o navegador descarrega o ficheiro.

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 a sua conta. Consulte limites e segurança.

Origem

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