# Empezar en 5 minutos

> De una cuenta nueva a la primera llamada a la API y al primer mensaje, paso a paso.

## Antes de empezar

Necesitas una cuenta en `app.messajo.com`. También una terminal con `curl`.

En los ejemplos, la API está en `https://api.messajo.com/v1`.

## 1. Crear la cuenta y la organización

1. Abre el panel y haz clic en **Crear cuenta**. Ingresa nombre, correo y contraseña.
2. Confirma el correo con el enlace que llega a tu bandeja de entrada.
3. Ponle un nombre a tu organización. Te conviertes en su **propietario**.

Todo en Messajo — conexiones, claves, destinos de eventos — pertenece a la organización, no a la persona. Consulta [Conceptos](/es/start/concepts/).

## 2. Activar el 2FA

La verificación en dos pasos es obligatoria para propietario y admin. Sin ella, el panel bloquea las áreas de la organización, incluida la creación de claves.

1. En **Configuración → Seguridad**, activa la **Verificación en dos pasos (2FA)**.
2. Escanea el código QR con una app autenticadora (Google Authenticator, 1Password, Authy…) y escribe el código de 6 dígitos.
3. Guarda los **códigos de respaldo** en un lugar seguro: son la salida si pierdes el teléfono.

## 3. Crear una clave de API

1. Abre **Claves de API** y haz clic en **Crear clave**.
2. Ponle un nombre (por ejemplo, `prueba`) y marca solo el permiso **Leer** (`read`), que basta para esta guía.
3. Deja **Todas las conexiones**, elige la validez y confirma.

La clave completa, que empieza con `mj_`, aparece **una sola vez**. Cópiala y guárdala en una variable de entorno:

```bash
export MESSAJO_API_KEY="mj_..."
```

Detalles en [Autenticación y claves de API](/es/api/authentication/).

## 4. Probar con GET /v1/me

`GET /v1/me` acepta cualquier clave válida y devuelve la organización y la propia clave. Es la forma más rápida de confirmar que la autenticación funciona.

**cURL**

```bash
curl https://api.messajo.com/v1/me \
  -H "Authorization: Bearer $MESSAJO_API_KEY"
```

**TypeScript**

```ts
// npm install @messajo/sdk
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });
const me = await messajo.me.get();
console.log(me.organization.name, me.api_key.permissions);
```

**Python**

```python
import os

import requests

response = requests.get(
    "https://api.messajo.com/v1/me",
    headers={"Authorization": f"Bearer {os.environ['MESSAJO_API_KEY']}"},
    timeout=10,
)
response.raise_for_status()
me = response.json()
print(me["organization"]["name"], me["api_key"]["permissions"])
```

Respuesta `200 OK`:

```json
{
  "organization": {
    "id": "Kq3vT9xZ2mWb7LpR4nYc8sDf1gHj6aEu",
    "name": "Acme",
    "slug": "acme"
  },
  "api_key": {
    "id": "Zt5rB8wQ1nXc4LmV7pYd2sGf9hJk3aRe",
    "name": "prueba",
    "start": "mj_A1b2c3d",
    "permissions": ["read"],
    "connection_ids": null,
    "kind": "org",
    "connection_id": null,
    "connection": null,
    "expires_at": "2027-01-01T00:00:00.000Z"
  },
  "request_id": "req_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b"
}
```

- `start` es el prefijo visible de la clave, el mismo que muestra el panel.
- `kind` es `org` (clave `mj_`) o `connection` (clave `mjc_`). En una clave de conexión, `connection_id` y `connection { id, channel, label }` identifican su conexión; en una de organización son `null`.
- `connection_ids: null` significa que la clave de organización vale para todas las conexiones; en una clave de conexión trae solo el id de su conexión.
- `expires_at` es `null` cuando la clave no vence.

¿Recibiste `401`? El cuerpo trae el `code` del error, por ejemplo [`missing_api_key`](/es/errors#missing_api_key) (falta el encabezado) o [`invalid_api_key`](/es/errors#invalid_api_key) (clave incorrecta o revocada).

## 5. Conectar un número de WhatsApp

1. En el panel, abre **Conexiones → Conectar WhatsApp**.
2. Elige el modo: **Mantener mi WhatsApp Business** (coexistencia: el número sigue en la app) o **Número nuevo, solo por la API**, y haz clic en **Continuar**.
3. Haz clic en **Abrir la ventana de Meta**, sigue el registro oficial de Meta en la ventana que se abre y espera a que el panel muestre **WhatsApp conectado.**

La conexión aparece como **Activa**, con un `id` con formato `conn_…`, que se usa en las llamadas de envío (la lista también está en `GET /v1/connections`). El paso a paso completo está en [Conectar WhatsApp](/es/connect/whatsapp/).

## 6. Enviar el primer mensaje

Crea una clave con el permiso `send` y llama a `POST /v1/messages`. Un mensaje libre solo sale hacia un contacto que te escribió en las últimas 24 horas; fuera de esa ventana, usa una plantilla aprobada (consulta [Conceptos](/es/start/concepts/)).

**cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "connection_id": "conn_...",
    "to": "5491122334455",
    "type": "text",
    "text": { "body": "¡Hola! Mensaje enviado con Messajo." }
  }'
```

**TypeScript**

```ts
const sent = await messajo.messages.send({
  connection_id: "conn_...",
  to: "5511999999999",
  type: "text",
  text: { body: "¡Hola! Mensaje enviado con Messajo." },
});
```

**n8n**

n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
    "connection_id": "conn_...",
    "to": "5491122334455",
    "type": "text",
    "text": { "body": "¡Hola! Mensaje enviado con Messajo." }
  }
```

El SDK genera el `Idempotency-Key` solo y repite con seguridad cuando falla la red. Consulta [SDK de TypeScript](/es/sdk/typescript/).

### Con clave de conexión

Si tu código solo habla con un número, crea una **clave de conexión** (`mjc_…`) en el panel de la propia conexión, en **Claves de API**. Ya sabe a qué conexión pertenece: el `connection_id` del cuerpo desaparece y la clave no alcanza otras conexiones. Una clave de organización (`mj_`) sigue exigiendo el `connection_id`.

**cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_CONNECTION_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "to": "5511999999999", "type": "text", "text": { "body": "¡Hola!" } }'
```

**TypeScript**

```ts
const sent = await messajo.connection().messages.send({
  to: "5511999999999",
  type: "text",
  text: { body: "¡Hola!" },
});
```

Ver [Tipos de clave](/es/api/authentication/#tipos-de-clave).

La respuesta es `201`:

```json
{
  "id": "msg_...",
  "external_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjQ",
  "status": "queued",
  "meta_status": "accepted",
  "conversation_id": "cnv_...",
  "contact_id": "ctc_...",
  "created_at": "2026-11-09T12:00:00.000Z"
}
```

`external_id` es el id de Meta (`wamid`). La entrega y la lectura llegan después, en el evento `message.status`. Fuera de la ventana, la respuesta es `422` [`outside_service_window`](/es/errors#outside_service_window). Cada tipo tiene su propia página en el grupo **Enviar mensajes**, empezando por [Enviar texto](/es/send/text/); los campos de cada uno están también en la [referencia de la API](/es/reference).

## 7. Recibir el webhook

1. En **Destinos de eventos**, registra la URL HTTPS que va a recibir los eventos. El panel muestra el secreto (`whsec_…`) una vez.
2. Responde `2xx` en hasta 10 segundos. Si no, Messajo reintenta con esperas crecientes durante hasta 24 horas.
3. Envía un mensaje a tu número: llega un evento `message.received`.

```json
{
  "id": "evt_...",
  "type": "message.received",
  "format": "normalized",
  "org": "Kq3vT9xZ2mWb7LpR4nYc8sDf1gHj6aEu",
  "connection": "conn_...",
  "channel": "whatsapp",
  "timestamp": "2026-11-09T12:00:00.000Z",
  "sequence": 1,
  "data": {}
}
```

El contenido de `data` depende del tipo de evento y del formato del destino. Antes de confiar en el cuerpo, verifica el encabezado `Messajo-Signature` con el secreto: consulta [Verificar la firma](/es/webhooks/verify-signature/). El catálogo completo está en [Eventos](/es/webhooks/events/).

## Próximos pasos

- [Conceptos](/es/start/concepts/): organizaciones, conexiones, claves y las dos capas de la API.
- [Autenticación y claves de API](/es/api/authentication/): permisos, validez y buenas prácticas.
- [Errores](/es/errors/) y [Límites](/es/api/limits/): qué manejar en tu código.
- [Verificar la firma](/es/webhooks/verify-signature/): obligatorio antes de ir a producción.
- [SDK de TypeScript](/es/sdk/typescript/), [Historial](/es/api/history/) y [Campañas](/es/guides/campaigns/).
- [Enviar texto](/es/send/text/): la primera de una página por tipo de mensaje.
- [Construir con IA](/es/start/build-with-ai/): `llms.txt`, Markdown por página y el archivo OpenAPI.
