Come aggiungere una chat di assistenza nativa alle tue app iOS e Android
Aggiungi una chat Helpium nativa alle tue app iOS e Android in un pomeriggio: la tua IA risponde subito, il tuo team subentra quando serve e le risposte arrivano come notifiche push.
Maximiliano Monge
Founder & editor at Helpium. Writing about AI-powered custom...
I tuoi clienti chiedono aiuto dove si trovano già: dentro la tua app. Mandarli su un sito web o a un indirizzo email aggiunge attrito proprio nel momento peggiore. Con gli SDK mobile di Helpium aggiungi una chat di assistenza nativa alle tue app iOS e Android in un pomeriggio. Il tuo agente IA risponde subito, il tuo team subentra quando serve e ogni conversazione finisce nella stessa Posta in arrivo di Helpium della chat web, dell'email e di WhatsApp.

Cosa ottieni
- Una chat nativa, non una web view. SwiftUI su iOS, viste native su Android. Sembra parte della tua app.
- Il tuo agente IA incluso. Le stesse conoscenze, procedure e azioni IA che hai configurato per il web rispondono dentro l'app.
- Un passaggio pulito. Il cliente tocca “Parla con una persona” e il tuo team risponde dalla Posta in arrivo in tempo reale.
- Notifiche push. Le risposte degli agenti raggiungono il cliente anche con l'app chiusa.
- Il tuo brand. Ogni colore, in modalità chiara e scura, e ogni testo, in ogni lingua.
Prima di iniziare: trova le tue chiavi in Helpium
Tutto ciò che serve all'integrazione si trova in una sola pagina del tuo workspace Helpium: Settings → Live Chat. Gli SDK mobile fanno parte del canale Live Chat, quindi le conversazioni della tua app seguono le stesse regole di IA, passaggio a una persona e orari di lavoro della chat del tuo sito.
La widget key si trova in Installation. Identifica il tuo workspace ed è pensata per essere pubblica: va dentro la tua app, proprio come va nell'HTML del tuo sito. Copiala con il pulsante Copy.

L'identity secret si trova in Customer identification. Clicca su Show o Copy. Questo è privato: conservalo sul tuo server, come variabile d'ambiente, insieme agli altri segreti. Non metterlo mai nell'app, nel controllo di versione o in una pagina web. Chiunque lo avesse potrebbe accedere come uno qualsiasi dei tuoi clienti. Se dovesse trapelare, clicca su Regenerate e aggiorna il tuo server.

Le credenziali push si collegano più in basso nella stessa pagina, in Mobile apps. Ti servono solo per le notifiche, quindi puoi tornarci al passo 4.

Passo 1: firma l'identità dei tuoi utenti sul tuo server
Quando un cliente ha effettuato l'accesso alla tua app, il tuo backend dice a Helpium chi è firmando un breve token con l'identity secret. La sua conversazione lo segue su tutti i dispositivi, la chat evita di chiedergli nome ed email e le azioni IA possono operare in sicurezza sul suo account. A Helpium non importa in che linguaggio sia scritto il tuo backend: il token è un JWT standard e ogni linguaggio ha una libreria per gestirlo.
Il token è un JWT firmato con HS256, che usa l'identity secret come chiave. Il suo payload contiene:
user_id: il tuo id per l'utente, come stringa. Usa questo oemail, meglio ancora entrambi.email: l'email dell'utente.exp: quando scade il token, in secondi Unix. Obbligatorio. Un'ora è più che sufficiente.
JSON
{
"user_id": "42",
"email": "jane@example.com",
"exp": 1767225600
}Aggiungi un endpoint richiamabile solo dagli utenti autenticati, per esempio GET /api/helpium-token, che costruisce questo token per l'utente corrente e lo restituisce. La tua app lo chiama dopo il login e passa il risultato all'SDK. Ecco la parte di firma in alcuni stack comuni; qualsiasi libreria JWT che supporti HS256 funziona allo stesso modo.
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();Nessun login nella tua app? Salta questo passo. La chat chiede nome ed email prima del primo messaggio.
Passo 2: aggiungi la chat alla tua app iOS
L'SDK iOS è un Swift Package (iOS 15+, nessun'altra dipendenza). In Xcode scegli File → Add Package Dependencies, incolla https://github.com/helpium-io/helpium-sdk e aggiungi il prodotto Helpium. Poi:
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()
La chat si apre direttamente sulla conversazione aperta del cliente. Mentre qualcuno sta scrivendo, il cliente lo vede, insieme allo stato dell'IA mentre cerca un'informazione.

Passo 3: aggiungi la chat alla tua app Android
L'SDK Android supporta Android 5.0 e successivi e funziona allo stesso modo da Java e Kotlin. Usa le normali viste Android, quindi si adatta a progetti vecchi e nuovi senza aggiungere androidx o Compose. Aggiungi JitPack e la dipendenza:
Gradle
// settings.gradle
maven { url "https://jitpack.io" }
// app/build.gradle
implementation "com.github.helpium-io:helpium-sdk:0.1.0"Poi, nel tuo codice:
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));
Usi React Native o Expo?
Il pacchetto @helpium/react-native avvolge entrambi gli SDK nativi, così ottieni la stessa chat nativa da JavaScript. Con Expo, usa una development build.
React Native
import { Helpium } from '@helpium/react-native';
Helpium.configure({ widgetKey: 'YOUR_WIDGET_KEY' });
Helpium.identify({ userJwt: token });
Helpium.present();Passo 4: attiva le notifiche push
Le notifiche push vengono inviate dai tuoi account Apple e Firebase, quindi arrivano dalla tua app e le chiavi restano tue. In Settings → Live Chat → Mobile apps, clicca su Connect accanto a ciascuna piattaforma:
- iOS: una chiave APNs (
.p8) del tuo account Apple Developer, con il suo Key ID, il Team ID e il tuo Bundle ID. - Android: il JSON del service account del tuo progetto Firebase.
Poi passa all'SDK il token del dispositivo e i tocchi. L'SDK non registra mai un proprio servizio di notifica, quindi funziona insieme alle notifiche che la tua app già invia.
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());Rendila tua
Per impostazione predefinita la chat usa il colore del brand delle tue impostazioni Live Chat. Ogni colore può anche essere impostato dall'app, separatamente per la modalità chiara e scura, con la possibilità di forzarne una:
Swift
Helpium.setAppearance(HelpiumAppearance(
light: HelpiumColors(
primary: "#0ea5e9",
headerBackground: "#0ea5e9",
headerText: "#ffffff"
),
dark: HelpiumColors(
primary: "#a78bfa",
background: "#0f0d1a",
surface: "#1c1830"
)
))


Anche ogni testo è tuo: il saluto, il testo di benvenuto, il segnaposto. Sostituiscili per lingua con le risorse stringa su Android e Localizable.strings su iOS, e aggiungi le lingue che Helpium non include:
XML
<!-- res/values-es/strings.xml -->
<string name="helpium_greeting">¡Hola! ¿Te ayudamos con tu pedido?</string>Provala prima del rilascio
- Dopo aver effettuato l'accesso, apri la chat: saluta il cliente senza chiedergli i suoi dati.
- Fai una domanda: l'IA risponde in pochi secondi.
- Tocca “Parla con una persona”: la conversazione compare nella tua Posta in arrivo di Helpium.
- Rispondi dalla Posta in arrivo: la risposta compare nell'app in tempo reale.
- Chiudi l'app e rispondi di nuovo: arriva una notifica push che apre la conversazione.
Prossimi passi
- Il repository dell'SDK su GitHub contiene il riferimento completo e app di esempio che puoi eseguire in un simulatore.
- Guide passo passo nel centro assistenza: iOS, Android, notifiche push e verifica dell'identità.
- Tutto per gli sviluppatori in un unico posto: helpium.io/developers.
Supporto con IA, senza prezzi da IA
Utenti illimitati. Un prezzo fisso. Servi i clienti con l'IA e con un team umano quando conta.
Continua a leggere
Automatizzare le risposte su Mercado Libre: una guida passo dopo passo
Una guida passo-passo per collegare Mercado Libre a Helpium e rispondere a domande e messaggi di acquisto con i dati reali di ogni annuncio.
Come unificare WhatsApp, Instagram e tutti i tuoi canali
Come funziona l'assistenza clienti quando WhatsApp, Instagram, Messenger, email, Mercado Libre, Shopify e la chat del tuo sito sono unificati in un'unica Posta in arrivo.
Come leggere la tua dashboard per capire se la tua IA funziona davvero
Attivare un chatbot IA è facile. Capire se sta aggiungendo valore o creando problemi in silenzio è un altro discorso. La risposta è nella tua dashboard, se sai cosa guardare.