SDK de Equilia

Las claves las crean los administradores de tu organización. Primero solicita el acceso al SDK desde tu panel —en Configuración, Facturación o la pestaña Claves SDK de una persona. Una vez que Equilia lo apruebe, un administrador de la organización podrá generar claves en la pestaña Claves SDK de cada persona. Cada clave se muestra una sola vez, al crearla: cópiala en ese momento y guárdala en un lugar seguro.

Cada clave está vinculada a una única organización y a una única persona. El cliente envía ambas en cada llamada y el servidor las contrasta con el alcance de la propia clave, de modo que una clave nunca puede alcanzar una organización o una persona para la que no fue emitida.

La URL base es el dominio de tu panel de Equilia, la misma dirección con la que inicias sesión.

Inicia una conversación, envía un mensaje y recibe una respuesta en streaming.

from equilia import EquiliaClient

client = EquiliaClient(
    api_key="sk_live_...",
    org_id="your-org-id",
    persona_id="your-persona-id",
    base_url="https://equilia.site",
)

result = client.launch(
    channel="sdk",
    name="Jane Doe",
    email="[email protected]",
    terms_accepted=True,
)

response = client.send_message(result.conversation_id, "Hello!")
print(response.message)

for chunk in client.send_message_stream(result.conversation_id, "Tell me more"):
    print(chunk, end="", flush=True)

Que se recojan y verifiquen los datos de contacto es un ajuste que tu administrador controla para cada persona (persona → Seguridad → Requerir validación de contactos). Es el ajuste más importante para los kioscos: uno de acceso libre que solo quiere conversación anónima puede dejarlo desactivado, mientras que uno que quiere contactos localizables debería activarlo.

No requerida (predeterminado)

Anónima, como un kiosco con código QR. No envíes ningún correo electrónico ni teléfono: si lo haces, se ignoran y nunca se almacenan. La conversación se puede usar de inmediato.

result = client.launch(channel="sdk", name="Kiosk Visitor", terms_accepted=True)
client.send_message(result.conversation_id, "Hello!")  # usable immediately

Requerida

Debes proporcionar un correo electrónico o un teléfono real que la persona pueda consultar. Se le envía un código de seis dígitos y los mensajes quedan bloqueados hasta que confirmes ese código.

El código nunca se te devuelve. Lo recibe directamente la persona; tú lo recoges de ella como lo haga tu aplicación o tu kiosco, y lo confirmas.

Hay dos casillas independientes y desmarcadas, y no son intercambiables. sms_consent (smsConsent en TypeScript y PHP) corresponde al código de verificación de un solo uso, que envía Equilia AI: su texto debe indicar a Equilia AI (L3R Street Furniture) como remitente y decir un mensaje por solicitud, pueden aplicarse tarifas de mensajes y datos, responde HELP para obtener ayuda y STOP para darte de baja. Enviar el código por SMS a un número de EE. UU. la requiere; sin ella, el lanzamiento se rechaza con sms_consent_required. org_sms_consent (orgSmsConsent) corresponde a los mensajes de tu empresa: la persona acepta recibirlos en el número que ha dado. Lanzar en el canal sms con un número de EE. UU. o de Canadá la requiere, y es lo que permite que tu persona le escriba más adelante en cualquier canal, así que conviene recogerla también en los lanzamientos de web y sdk; se registra sea cual sea el canal. Un lanzamiento en el canal sms que además envía un código necesita las dos casillas, aunque quien envíe solo sms_consent en ese canal sigue funcionando. Para un número de EE. UU. en el canal sms, tu persona debe tener además un número de EE. UU.; si no, el lanzamiento se rechaza con sms_us_unavailable. El correo electrónico y los números de fuera de EE. UU. y Canadá no se ven afectados.

result = client.launch(
    channel="sdk", name="Jane Doe", email="[email protected]", terms_accepted=True
)
# Jane receives the code by email. Collect it from her, then confirm:
client.validate(result.conversation_id, "123456")
client.send_message(result.conversation_id, "Hello!")  # now works

Reenviar un código

Si el código no llegó o caducó antes de introducirlo, pide uno nuevo para los mismos datos de contacto en lugar de empezar de cero. El código anterior deja de funcionar de inmediato y las peticiones repetidas están limitadas: deja al menos un minuto entre ellas.

client.resend(conversation_id)

Confirmar y enviar mensajes en procesos distintos

La confirmación se recuerda en la instancia del cliente que la hizo. Si confirmas el código en una petición web pero envías los mensajes desde un proceso en segundo plano o una invocación serverless posterior, pasa el código a ese segundo cliente para que pueda reconstruir la confirmación localmente; de lo contrario, todos los mensajes se rechazan aunque el contacto esté verificado.

# Process A — launches and confirms
client.validate(conversation_id, "123456")

# Process B — a fresh client, same conversation
worker_client.attach_verification(conversation_id, "123456")
worker_client.send_message(conversation_id, "Hello!")

Puedes iniciar en cualquier canal, no solo en el canal de chat del SDK. Un inicio por vídeo devuelve un id de conversación: constrúyele la URL de la página y hazla llegar a la persona por el medio que ya utilices. La llamada solo se establece cuando abre esa página, y únicamente si el contacto ha quedado validado. Los SMS tienen reglas adicionales: a un número de EE. UU. o de Canadá solo se le envían mensajes cuando la persona lo ha aceptado (véase más arriba) o ha escrito primero a tu número; a un número de EE. UU. solo se le puede escribir desde un número de EE. UU.; y quien responde STOP deja de recibir mensajes de tu empresa, en cualquier país, hasta que responde START.

result = client.launch(
    channel="video", name="Jane Doe", email="[email protected]", terms_accepted=True
)
# Build the page link and deliver it to Jane yourself, then:
link = client.conversation_url(result.conversation_id)
client.validate(result.conversation_id, "123456")

WhatsApp, Telegram, Messenger e Instagram

Estos funcionan de otra forma: al iniciar todavía no existe ninguna conversación. Recibes un código corto para mostrárselo a la persona, y ella lo envía como su primer mensaje en ese canal; eso es lo que demuestra que llegó a través de ti y no que es alguien que encontró tu número por su cuenta. No hay paso de confirmación, y la conversación resultante aparece en el panel y no a través del cliente.

Cuando una persona está ejecutando un flujo guiado, la respuesta incluye el nodo actual y las opciones disponibles en él. Devuelve la opción elegida para avanzar el flujo. Usa la llamada sin streaming para esto: el streaming solo devuelve texto, así que el estado del flujo nunca te llega.

result = client.send_message(conversation_id, "I need support")
if result.guided_flow:
    option = result.guided_flow["options"][0]
    result = client.send_message(
        conversation_id, option["label"], guided_flow_edge_id=option["edge_id"]
    )

Los fallos de autenticación lanzan un tipo de error propio, separado del error general de la API. Esa separación es deliberada: el estado recuperable más habitual, una conversación que aún espera su código, llega como un 403 y conviene tratarlo en vez de mezclarlo con todo lo demás.

from equilia import EquiliaAPIError, EquiliaAuthError

try:
    client.send_message(conversation_id, "Hello!")
except EquiliaAuthError as e:
    # 401/403 — bad key, wrong scope, or the code is not confirmed yet
    print(f"Auth: {e}")
except EquiliaAPIError as e:
    print(f"API {e.status_code}: {e}")

La URL base debe usar HTTPS. Tu clave viaja como token en cada una de las peticiones, así que el cliente se niega a arrancar con una dirección sin cifrar en lugar de dejar que la primera clave salga en claro; las direcciones de desarrollo local son la única excepción.

Nunca se siguen redirecciones. Nada en esta API redirige, y seguir una repetiría tu clave y el cuerpo de la petición en la dirección que indicara la respuesta.