Cómo agregar un chat de soporte nativo a tus apps de iOS y Android

Tus clientes piden ayuda donde ya están: dentro de tu app. Mandarlos a un sitio web o a un email suma fricción en el peor momento. Con los SDKs móviles de Helpium agregas un chat de soporte nativo a tus apps de iOS y Android en una tarde. Tu agente de IA responde al instante, tu equipo toma la conversación cuando hace falta y todo llega al mismo inbox de Helpium que tu chat web, el email y WhatsApp.

Qué obtienes

• Un chat nativo, no una web view. SwiftUI en iOS, vistas nativas en Android. Se siente parte de tu app.
• Tu agente de IA incluido. El mismo conocimiento, procedimientos y Acciones IA que configuraste para la web responden dentro de la app.
• Un traspaso prolijo. El cliente toca “Hablar con una persona” y tu equipo responde desde el inbox en tiempo real.
• Notificaciones push. Las respuestas de los agentes llegan aunque el cliente tenga la app cerrada.
• Tu marca. Cada color, en modo claro y oscuro, y cada texto, en cada idioma.

Antes de empezar: encuentra tus claves en Helpium

Todo lo que necesita la integración está en una sola página de tu workspace de Helpium: Configuración → Live Chat. Los SDKs móviles son parte del canal Live Chat, así que las conversaciones de tu app siguen las mismas reglas de IA, traspaso y horario de atención que el chat de tu sitio.

La clave del widget (widget key) está en Instalación. Identifica a tu workspace y es pública: va dentro de tu app, igual que va en el HTML de tu sitio. Cópiala con el botón Copiar.

El secreto de identidad (identity secret) está en Identificación de clientes. Haz clic en Mostrar o Copiar. Este es privado: guárdalo en tu servidor, como variable de entorno, junto a tus otros secretos. Nunca lo pongas en la app, en el repositorio ni en una página web: con él cualquiera podría hacerse pasar por tus clientes. Si alguna vez se filtra, haz clic en Regenerar y actualiza tu servidor.

Las credenciales de push se conectan más abajo en la misma página, en Apps móviles. Solo hacen falta para las notificaciones, así que puedes volver a esto en el paso 4.

Paso 1: firma la identidad de tus usuarios en tu servidor

Cuando un cliente inició sesión en tu app, tu backend le dice a Helpium quién es firmando un token corto con el secreto de identidad. Así su conversación lo sigue entre dispositivos, el chat no le pide nombre ni email y las Acciones IA pueden actuar sobre su cuenta de forma segura. No importa en qué lenguaje esté tu backend: el token es un JWT estándar y todos los lenguajes tienen una librería para generarlo.

El token es un JWT firmado con HS256, usando el secreto de identidad como clave. Su payload lleva:

• user_id: el id del usuario en tu sistema, como texto. Usa este o email, idealmente los dos.
• email: el email del usuario.
• exp: cuándo vence el token, en segundos Unix. Obligatorio. Con una hora alcanza.

JSON

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

Agrega un endpoint que solo puedan llamar usuarios con sesión iniciada, por ejemplo GET /api/helpium-token, que arme este token para el usuario actual y lo devuelva. Tu app lo llama después del login y le pasa el resultado al SDK. Esta es la parte de la firma en algunos stacks comunes; cualquier librería JWT que soporte HS256 funciona igual.

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

¿Tu app no tiene login? Saltea este paso. El chat pide nombre y email antes del primer mensaje.

Paso 2: agrega el chat a tu app de iOS

El SDK de iOS es un Swift Package (iOS 15+, sin otras dependencias). En Xcode, elige File → Add Package Dependencies, pega https://github.com/helpium-io/helpium-sdk y agrega el producto Helpium. Después:

Swift

import Helpium

// Al iniciar la app
Helpium.configure(widgetKey: "TU_WIDGET_KEY")

// Después del login, con el token de tu servidor
Helpium.identify(userJwt: token)

// Desde tu botón de Ayuda
Helpium.present()

El chat abre directo en la conversación abierta del cliente. Mientras alguien escribe, el cliente lo ve, y también el estado de la IA cuando está buscando algo.

Paso 3: agrega el chat a tu app de Android

El SDK de Android funciona desde Android 5.0 y se usa igual desde Java y Kotlin. Usa vistas nativas de Android, así que encaja en proyectos viejos y nuevos sin sumar androidx ni Compose. Agrega JitPack y la dependencia:

Gradle

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

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

Después, en tu código:

Java

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

// Después del login, con el token de tu servidor
Helpium.identify(token);

// Desde tu botón de Ayuda
helpButton.setOnClickListener(v -> Helpium.present(this));

¿Usas React Native o Expo?

El paquete @helpium/react-native envuelve los dos SDKs nativos, así que tienes el mismo chat nativo desde JavaScript. Con Expo, usa un development build.

React Native

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

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

Paso 4: activa las notificaciones push

Las notificaciones salen de tus propias cuentas de Apple y Firebase, así que llegan desde tu app y tú controlas las claves. En Configuración → Live Chat → Apps móviles, haz clic en Conectar junto a cada plataforma:

• iOS: una key de APNs (.p8) de tu cuenta de Apple Developer, con su Key ID, tu Team ID y tu Bundle ID.
• Android: el JSON de la cuenta de servicio de tu proyecto de Firebase.

Después pásale al SDK el token del dispositivo y los toques. Nunca registra su propio servicio de notificaciones, así que convive con las notificaciones que tu app ya envía.

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

// Activity de inicio: una notificación tocada con la app cerrada
Helpium.handlePush(this, getIntent().getExtras());

Hazlo tuyo

Por defecto el chat usa el color de marca de tu configuración de Live Chat. Además, cada color se puede definir desde la app, por separado para modo claro y oscuro, con la opción de forzar uno:

Swift

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

Todos los textos también son tuyos: el saludo, el texto de bienvenida, el placeholder. Reemplázalos por idioma con recursos de texto en Android y Localizable.strings en iOS, y suma idiomas que Helpium no trae:

XML

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

Pruébalo antes de publicar

1. Con sesión iniciada, abre el chat: saluda al cliente sin pedirle sus datos.
2. Haz una pregunta: la IA responde en segundos.
3. Toca “Hablar con una persona”: la conversación aparece en tu inbox de Helpium.
4. Responde desde el inbox: la respuesta aparece en la app en tiempo real.
5. Cierra la app y responde de nuevo: llega una notificación push que abre la conversación.

Próximos pasos

• El repositorio del SDK en GitHub tiene la referencia completa y apps de ejemplo para probar en un simulador.
• Guías paso a paso en el centro de ayuda: iOS, Android, notificaciones push y verificación de identidad.
• Todo para desarrolladores en un solo lugar: helpium.io/developers.