POST /api/start

Crea una actividad y obtén su botón de lanzamiento. La tarjeta aparece cuando un celular 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 celular 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 celulares. Consulta un botón, muchos celulares.
`keepAlive`	boolean	`true` reinicia la tarjeta cada 7 horas, antes de que iOS la cierre. Cada reinicio genera una alerta. Úsalo en una cuenta regresiva 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.

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

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 celular. group está vacío si no se envió ninguno.

{
  "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 celular, un toque abre la actividad. En una computadora, un clic muestra un código QR para escanear con el celular.

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, agrega `&theme=dark` y cambia `color-scheme:light` por `color-scheme:dark` en el `style` del iframe.
`type`	`track` (predeterminado), `launch`, `add`	El ícono, 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 ícono 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 celular. 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).