Guias e tutoriais

Como adicionar um chat de suporte nativo aos seus apps iOS e Android

Adicione um chat nativo da Helpium aos seus apps iOS e Android em uma tarde: sua IA responde na hora, sua equipe assume quando for preciso e as respostas chegam como notificações push.

Maximiliano Monge

Maximiliano Monge

Founder & editor at Helpium. Writing about AI-powered custom...

· 7 min
Como adicionar um chat de suporte nativo aos seus apps iOS e Android

Seus clientes pedem ajuda onde já estão: dentro do seu app. Mandá-los para um site ou um endereço de e-mail cria atrito no pior momento. Com os SDKs mobile da Helpium, você adiciona um chat de suporte nativo aos seus apps iOS e Android em uma tarde. Seu agente de IA responde na hora, sua equipe assume quando for preciso, e cada conversa chega à mesma caixa de entrada da Helpium que recebe o chat do site, o e-mail e o WhatsApp.

Chat da Helpium no iOS, pronto para a primeira mensagem
O chat abre pronto para digitar, com a sua saudação e respostas instantâneas.

O que você ganha

  • Um chat nativo, não uma web view. SwiftUI no iOS, views nativas no Android. Parece parte do seu app.
  • Seu agente de IA incluído. O mesmo conhecimento, os mesmos procedimentos e as mesmas ações de IA que você configurou para a web respondem dentro do app.
  • Uma transferência tranquila. O cliente toca em “Falar com uma pessoa” e sua equipe responde pela caixa de entrada em tempo real.
  • Notificações push. As respostas dos agentes chegam ao cliente mesmo com o app fechado.
  • A sua marca. Todas as cores, em modo claro e escuro, e todos os textos, em todos os idiomas.

Antes de começar: encontre suas chaves na Helpium

Tudo o que a integração precisa está em uma única página do seu workspace da Helpium: Configurações → Live Chat. Os SDKs mobile fazem parte do canal de Live Chat, então as conversas do seu app seguem as mesmas regras de IA, transferência e horário de atendimento do chat do seu site.

A widget key fica em Instalação. Ela identifica o seu workspace e foi feita para ser pública: vai dentro do seu app, assim como vai no HTML do seu site. Copie com o botão Copiar.

O campo Widget key na Helpium, nas configurações de Live Chat
Configurações → Live Chat → Instalação: a widget key vai no seu app.

O identity secret fica em Identificação do cliente. Clique em Mostrar ou Copiar. Este é privado: guarde no seu servidor, como variável de ambiente, junto com os seus outros segredos. Nunca o coloque no app, no controle de versão ou em uma página web. Qualquer pessoa com ele poderia entrar como qualquer um dos seus clientes. Se ele vazar, clique em Gerar novamente e atualize o seu servidor.

O campo Identity secret na Helpium, oculto, com os botões Mostrar, Copiar e Gerar novamente
Configurações → Live Chat → Identificação do cliente: o identity secret fica no seu servidor.

As credenciais de push são conectadas mais abaixo na mesma página, em Apps mobile. Você só precisa delas para as notificações, então pode voltar a isso no passo 4.

A seção Apps mobile na Helpium com botões Conectar para iOS e Android
Configurações → Live Chat → Apps mobile: conecte Apple e Firebase para enviar notificações push.

Passo 1: assine a identidade dos seus usuários no seu servidor

Quando um cliente está logado no seu app, o seu backend diz à Helpium quem ele é assinando um token curto com o identity secret. Assim, a conversa dele o acompanha entre dispositivos, o chat não pede nome e e-mail, e as ações de IA podem agir com segurança na conta dele. A Helpium não se importa com a linguagem do seu backend: o token é um JWT padrão, e toda linguagem tem uma biblioteca para isso.

O token é um JWT assinado com HS256, usando o identity secret como chave. O payload leva:

  • user_id: o seu próprio id do usuário, como string. Use este ou email, de preferência os dois.
  • email: o e-mail do usuário.
  • exp: quando o token expira, em segundos Unix. Obrigatório. Uma hora é suficiente.

JSON

{
  "user_id": "42",
  "email": "jane@example.com",
  "exp": 1767225600
}

Adicione um endpoint que só usuários logados possam chamar, por exemplo GET /api/helpium-token, que monte esse token para o usuário atual e o devolva. Seu app o chama após o login e passa o resultado ao SDK. Aqui está a parte da assinatura em algumas stacks comuns; qualquer biblioteca JWT que suporte HS256 funciona do mesmo jeito.

Node.js

// npm install jsonwebtoken
const jwt = require('jsonwebtoken');

const token = jwt.sign(
  { user_id: String(user.id), email: user.email },
  process.env.HELPIUM_IDENTITY_SECRET,
  { algorithm: 'HS256', expiresIn: '1h' }
);

Python

# pip install pyjwt
import os, time, jwt

token = jwt.encode(
    {"user_id": str(user.id), "email": user.email, "exp": int(time.time()) + 3600},
    os.environ["HELPIUM_IDENTITY_SECRET"],
    algorithm="HS256",
)

PHP

// composer require firebase/php-jwt
use Firebase\JWT\JWT;

$token = JWT::encode([
    'user_id' => (string) $user->id,
    'email' => $user->email,
    'exp' => time() + 3600,
], getenv('HELPIUM_IDENTITY_SECRET'), 'HS256');

Ruby

# gem install jwt
require 'jwt'

token = JWT.encode(
  { user_id: user.id.to_s, email: user.email, exp: Time.now.to_i + 3600 },
  ENV.fetch('HELPIUM_IDENTITY_SECRET'),
  'HS256'
)

Java

// io.jsonwebtoken:jjwt-api + jjwt-impl + jjwt-jackson
String token = Jwts.builder()
    .claim("user_id", String.valueOf(user.getId()))
    .claim("email", user.getEmail())
    .expiration(new Date(System.currentTimeMillis() + 3_600_000))
    .signWith(Keys.hmacShaKeyFor(System.getenv("HELPIUM_IDENTITY_SECRET").getBytes(StandardCharsets.UTF_8)), Jwts.SIG.HS256)
    .compact();

Seu app não tem login? Pule este passo. O chat pede nome e e-mail antes da primeira mensagem.

Passo 2: adicione o chat ao seu app iOS

O SDK para iOS é um Swift Package (iOS 15+, sem outras dependências). No Xcode, escolha File → Add Package Dependencies, cole https://github.com/helpium-io/helpium-sdk e adicione o produto Helpium. Depois:

Swift

import Helpium

// At launch
Helpium.configure(widgetKey: "YOUR_WIDGET_KEY")

// After login, with the token from your server
Helpium.identify(userJwt: token)

// From your Help button
Helpium.present()

Uma conversa no chat da Helpium no iOS, com respostas da IA e de um agente
Respostas da IA, um link da sua central de ajuda e uma resposta da equipe, agrupados como em um chat nativo.

O chat abre direto na conversa aberta do cliente. Enquanto alguém está escrevendo, o cliente vê, e também vê o status da IA enquanto ela consulta algo.

Indicador de digitação no chat da Helpium no iOS
Pontinhos de digitação enquanto a IA ou um agente escreve.

Passo 3: adicione o chat ao seu app Android

O SDK para Android é compatível com Android 5.0 ou superior e funciona igual em Java e Kotlin. Ele usa views simples do Android, então se encaixa em projetos antigos e novos sem adicionar androidx nem Compose. Adicione o JitPack e a dependência:

Gradle

// settings.gradle
maven { url "https://jitpack.io" }

// app/build.gradle
implementation "com.github.helpium-io:helpium-sdk:0.1.0"

Depois, no seu código:

Java

// Application.onCreate()
Helpium.configure(this, "YOUR_WIDGET_KEY");

// After login, with the token from your server
Helpium.identify(token);

// From your Help button
helpButton.setOnClickListener(v -> Helpium.present(this));

Uma conversa no chat da Helpium no Android
O mesmo chat no Android, feito com views nativas.

Usa React Native ou Expo?

O pacote @helpium/react-native envolve os dois SDKs nativos, então você tem o mesmo chat nativo a partir do JavaScript. Com o Expo, use um development build.

React Native

import { Helpium } from '@helpium/react-native';

Helpium.configure({ widgetKey: 'YOUR_WIDGET_KEY' });
Helpium.identify({ userJwt: token });
Helpium.present();

Passo 4: ative as notificações push

As notificações push são enviadas das suas próprias contas Apple e Firebase, então saem do seu app e as chaves ficam com você. Em Configurações → Live Chat → Apps mobile, clique em Conectar ao lado de cada plataforma:

  • iOS: uma chave APNs (.p8) da sua conta Apple Developer, com o Key ID, o Team ID e o seu Bundle ID.
  • Android: o JSON da service account do seu projeto Firebase.

Depois, entregue ao SDK o token do dispositivo e os toques. Ele nunca registra um serviço de notificações próprio, então funciona junto com as notificações que o seu app já envia.

iOS

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Helpium.setPushToken(deviceToken)
}

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse) async {
    Helpium.handlePush(response.notification.request.content.userInfo)
}

Android

@Override
public void onNewToken(@NonNull String token) {
    Helpium.setPushToken(token);
}

// Launcher activity: a notification tapped with the app closed
Helpium.handlePush(this, getIntent().getExtras());

Deixe com a sua cara

Por padrão, o chat usa a cor da marca definida nas suas configurações de Live Chat. Todas as cores também podem ser definidas pelo app, separadamente para modo claro e escuro, com a opção de forçar um deles:

Swift

Helpium.setAppearance(HelpiumAppearance(
    light: HelpiumColors(
        primary: "#0ea5e9",
        headerBackground: "#0ea5e9",
        headerText: "#ffffff"
    ),
    dark: HelpiumColors(
        primary: "#a78bfa",
        background: "#0f0d1a",
        surface: "#1c1830"
    )
))

Chat da Helpium com um tema azul claro
Um tema claro com cabeçalho colorido.

Chat da Helpium com um tema roxo escuro
Um tema escuro, forçado independentemente da configuração do celular.

Chat da Helpium no Android com um tema verde
Qualquer paleta funciona também no Android.

Todos os textos também são seus: a saudação, o texto de boas-vindas, o placeholder. Sobrescreva-os por idioma com string resources no Android e Localizable.strings no iOS, e adicione idiomas que a Helpium não traz:

XML

<!-- res/values-es/strings.xml -->
<string name="helpium_greeting">¡Hola! ¿Te ayudamos con tu pedido?</string>

Teste antes de publicar

  1. Logado, abra o chat: ele cumprimenta o cliente sem pedir os dados dele.
  2. Faça uma pergunta: a IA responde em segundos.
  3. Toque em “Falar com uma pessoa”: a conversa aparece na sua caixa de entrada da Helpium.
  4. Responda pela caixa de entrada: a resposta aparece no app em tempo real.
  5. Feche o app e responda de novo: chega uma notificação push que abre a conversa.

Próximos passos

Suporte com IA, sem preço de IA

Usuários ilimitados. Um preço fixo. Atenda clientes com IA e com uma equipe humana quando importa.

Continue lendo