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
Founder & editor at Helpium. Writing about AI-powered custom...
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.

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 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.

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.

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 ouemail, 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()
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.

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));
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"
)
))


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
- Logado, abra o chat: ele cumprimenta o cliente sem pedir os dados dele.
- Faça uma pergunta: a IA responde em segundos.
- Toque em “Falar com uma pessoa”: a conversa aparece na sua caixa de entrada da Helpium.
- Responda pela caixa de entrada: a resposta aparece no app em tempo real.
- Feche o app e responda de novo: chega uma notificação push que abre a conversa.
Próximos passos
- O repositório do SDK no GitHub tem a referência completa e apps de exemplo que você pode rodar em um simulador.
- Guias passo a passo na central de ajuda: iOS, Android, notificações push e verificação de identidade.
- Tudo para desenvolvedores em um só lugar: helpium.io/developers.
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
Automatize as respostas do Mercado Libre: um guia passo a passo
Um guia passo a passo para conectar o Mercado Libre ao Helpium e responder perguntas e mensagens de compra com os dados reais de cada anúncio.
Como unificar WhatsApp, Instagram e todos os seus canais
Como funciona o atendimento ao cliente quando WhatsApp, Instagram, Messenger, e-mail, Mercado Livre, Shopify e o chat do seu site estão unificados em uma única caixa de entrada.
Como ler seu painel para saber se a sua IA está mesmo funcionando
Ligar um chatbot com IA é fácil. Saber se ele está agregando valor ou criando problemas em silêncio é outra história. A resposta está no seu painel, se você souber o que olhar.