POST /api/start
Crea una actividad y obtén su botón de lanzamiento. La tarjeta aparece cuando un teléfono abre el botón.
Envía la clave en el encabezado x-api-key en cada llamada. Todas las solicitudes son Content-Type: application/json, y los nombres de campo son camelCase exacto (accentColorHex, nunca accent_color_hex). Los errores están en errores y límites.
Cuerpo
| Campo | Tipo | Instrucciones |
|---|---|---|
state | object | Obligatorio. Lo que muestra la tarjeta. Consulta diseños y el objeto state. |
widgetContainerId | string | Obligatorio. Cualquier texto que identifique el widget, por ejemplo «pizza-tracker». Envía el mismo valor en cada llamada posterior para este widget. Un teléfono conserva una actividad por contenedor. |
group | string | Una etiqueta, para que una sola llamada pueda actualizar o finalizar muchas actividades. |
brand | object | El nombre y la marca de la actividad. Consulta el objeto brand. |
reuse | boolean | true permite que un botón de lanzamiento sirva a muchos teléfonos. Consulta un botón, muchos móviles. |
keepAlive | boolean | true reinicia la tarjeta cada 7 horas, antes de que iOS la cierre. Cada reinicio genera una alerta. Úsalo en una cuenta atrás o en cualquier cosa que dure más de 8 horas. Consulta actividades de larga duración. |
webhookIdentifier | string | Envía los eventos de webhook de esta actividad al endpoint con este identificador. Consulta webhooks. |
Inicio básico
El inicio más simple: una barra de progreso con un titular y un logo.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
curl -X POST https://api.webliveactivity.com/api/start \ -H 'Content-Type: application/json' \ -H 'x-api-key: wla_your_key' \ -d '{ "widgetContainerId": "acme-orders", "brand": { "title": "Order #1234" }, "state": { "layout": "progress", "primaryText": "Order received", "progress": 0.1, "accentColorHex": "#0A84FF", "headerIconUrl": "https://acme.example/logo.png" } }'
Inicio con todas las opciones
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
curl -X POST https://api.webliveactivity.com/api/start \ -H 'Content-Type: application/json' \ -H 'x-api-key: wla_your_key' \ -d '{ "widgetContainerId": "acme-orders", "group": "order-tracker", "keepAlive": true, "webhookIdentifier": "staging", "brand": { "title": "Order #1234", "name": "Acme", "logo": "https://acme.example/logo.png", "description": "Track your Acme order from kitchen to door", "color": "#06C167" }, "state": { "layout": "progress", "primaryText": "Order received", "secondaryText": "We will start soon", "progress": 0.1 } }'
Respuesta
Responde 201. Guarda el activityId para las actualizaciones y los finales. userId es el mismo id, con el nombre que usan las apps del teléfono. group está vacío si no se ha enviado ninguno.
1 2 3 4 5 6 7 8 9 10
{ "ok": true, "activityId": "act-8f2cqa4mx7rd", "userId": "act-8f2cqa4mx7rd", "group": "order-tracker", "widgetContainerId": "acme-orders", "links": { "iframe": "<iframe src=\"https://api.webliveactivity.com/embed/button?type=track&userId=act-8f2cqa4mx7rd\" width=\"340\" height=\"95\" style=\"border:0;color-scheme:light\"></iframe>" } }
El botón de lanzamiento
Pon links.iframe en una página web. En un móvil, un toque abre la actividad. En un ordenador, un clic muestra un código QR para escanear con el móvil.
El src del iframe acepta tres ajustes opcionales:
| Ajuste | Valores | Instrucciones |
|---|---|---|
color | Un color hexadecimal de 6 dígitos, sin # | El color del botón. Ejemplo: &color=06C167. Un color claro lleva texto oscuro. Predeterminado: el color de type. |
theme | light (predeterminado), dark | El color del texto «Powered By» bajo el botón. En una página oscura, añade &theme=dark y cambia color-scheme:light por color-scheme:dark en el style del iframe. |
type | track (predeterminado), launch, add | El icono, el texto y el color predeterminado del botón. Los grupos de push usan notify, subscribe o follow. |
El fondo es transparente. Solo se puede cambiar el color: el icono y el texto vienen de type, y una línea «Powered By» aparece bajo el botón en todos los planes.
La página que aloja el botón pasa a ser el sitio que se muestra con la actividad en el teléfono. La API no puede definirlo. El botón no carga en una página que oculta su referrer (Referrer-Policy: no-referrer o same-origin, o referrerpolicy="no-referrer" en el iframe).
