SDK de Equilia

Genera una desde tu panel: Personas → elige una persona → Claves SDK → Generar nueva clave. La clave se muestra una sola vez, así que cópiala de inmediato: no se puede recuperar después.

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.

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.

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.