# Inicio rápido

> Crea una clave de API de watsi, lista tus contactos y conversaciones y crea un contacto con una escritura segura de reintentar, en cinco minutos.

Source: https://docs.watsi.ai/quickstart

En cinco minutos vas a crear una clave, leer tus contactos y tus conversaciones, y crear un contacto. Todas las llamadas van a `https://api.watsi.ai/v1/actions/…` con tu clave en el encabezado `Authorization`.

> **Antes de empezar**

- Una cuenta de watsi en la que seas propietario o administrador (son quienes pueden crear claves).
- `curl`, o cualquier cliente HTTP.

### Crea una clave de API

Abre [watsi.ai/workspace/settings/api-keys](https://watsi.ai/workspace/settings/api-keys) (**Configuración → Desarrollador → Claves API**) y pulsa **Crear Clave API**. Los permisos de lectura vienen marcados; para el último paso marca también **`contacts:write`**. Copia la clave: empieza por `wats_live_` y sólo se muestra una vez.

```bash
export WATSI_API_KEY="wats_live_…"
```

### Lista tus contactos

`contacts/list` pagina con `limit` y `offset` y te dice cuántos hay en total.

```bash Solicitud
curl "https://api.watsi.ai/v1/actions/contacts/list?limit=2" \
  -H "Authorization: Bearer $WATSI_API_KEY"
```

```json Respuesta
{
  "data": [
    {
      "id": "c41f7b8a-2e6d-4a93-8b05-1d7e9f3c6a24",
      "name": "María García",
      "phone_number": "5215512345678",
      "wa_id": "5215512345678",
      "email": null,
      "assigned_user_id": null,
      "last_message_at": "2026-10-30T16:04:11.000Z",
      "created_at": "2026-10-12T09:15:40.000Z",
      "relationship": "business"
    }
  ],
  "total": 248,
  "limit": 2,
  "offset": 0
}
```

Si la respuesta es `401`, revisa que el encabezado sea exactamente `Authorization: Bearer wats_live_…`. Los demás códigos están en [Manejo de errores](/error-handling).

### Lista tus conversaciones

`conversations/list` devuelve las más activas primero, el `total` que coincide con tus filtros y `hasMore` para saber si hay otra página.

```bash Solicitud
curl "https://api.watsi.ai/v1/actions/conversations/list?limit=2&awaitingReply=true" \
  -H "Authorization: Bearer $WATSI_API_KEY"
```

```json Respuesta
{
  "data": [
    {
      "id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
      "href": "/chats/c41f7b8a-2e6d-4a93-8b05-1d7e9f3c6a24",
      "customer_name": "María García",
      "customer_phone": "5215512345678",
      "status": "active",
      "funnel_stage": "Interesado",
      "assignee_name": "Ana López",
      "last_message_at": "2026-10-30T16:04:11.000Z",
      "last_message_at_local": "2026-10-30 10:04",
      "last_message_preview": "Hola, ¿tienen citas para mañana?",
      "created_at": "2026-10-12T09:15:40.000Z",
      "created_at_local": "2026-10-12 03:15",
      "summary": null,
      "relationship": "business"
    }
  ],
  "hasMore": true,
  "total": 17,
  "totalIsCapped": false,
  "period": null,
  "timezone": "America/Mexico_City"
}
```

`awaitingReply=true` deja sólo las conversaciones donde el cliente escribió al último y nadie le ha respondido. Los campos `*_local` ya están en la zona horaria del espacio de trabajo.

### Crea un contacto

`contacts/create` crea el contacto o, si ya existe uno con ese teléfono, `wa_id` o correo, lo actualiza. Manda un `Idempotency-Key` para poder reintentar sin miedo: si repites la misma solicitud con la misma clave en los siguientes 30 segundos, recibes la misma respuesta sin que se escriba dos veces.

```bash Solicitud
curl -X POST "https://api.watsi.ai/v1/actions/contacts/create" \
  -H "Authorization: Bearer $WATSI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c2a1e-alta-maria-perez" \
  -d '{
    "name": "María Pérez",
    "phone_number": "5215598765432",
    "metadata": { "source": "formulario-web" }
  }'
```

```json Respuesta
{
  "contact": {
    "id": "5e8a2c71-9d04-4b3f-a6e1-7c2f9b5d3a80",
    "name": "María Pérez",
    "phone_number": "5215598765432",
    "wa_id": null,
    "email": null,
    "assigned_user_id": null,
    "last_message_at": null,
    "created_at": "2026-10-30T17:12:03.000Z",
    "relationship": null
  },
  "created": true
}
```

Es una escritura sólo de CRM: no abre una conversación ni dispara automatizaciones. Si la clave no tiene `contacts:write` recibes `403 FORBIDDEN`.

## Siguientes pasos

- [Autenticación](/guides/authentication)
    Todos los alcances y los límites.
- [Todas las rutas](/api/overview)
    El índice completo de la API.
- [Webhooks](/webhooks)
    Recibe eventos sin consultar.
- [Servidor MCP](/mcp)
    Conecta tu asistente de IA.
