> ## Documentation Index
> Fetch the complete documentation index at: https://devs.izap.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Solución de problemas

> Soluciones a los problemas más frecuentes de los desarrolladores con la API REST y el servidor MCP de iZap.

Cada entrada parte del síntoma que ves. Para los errores de conexión de
WhatsApp que devuelve Meta (como `#2655093` o `#3441038`), consulta la página
del centro de ayuda
[Problemas de conexión con WhatsApp](https://docs.izap.ai/es/troubleshoot-whatsapp-connection).

## `GET /api/v1/chats/{business_id}` devuelve conversaciones de prueba

El parámetro de consulta `kind` tiene como valor predeterminado `trainer`, que
devuelve las conversaciones de prueba del AI Trainer. Pasa `kind=real` para las
conversaciones reales de WhatsApp, o `kind=all` para ambas. Cualquier otro valor
devuelve `400`.

## Consultar con `since` devuelve mensajes que ya viste

`since` es una marca de tiempo ISO-8601, exclusiva (estrictamente más reciente),
y se trata como UTC cuando no tiene desfase. Filtra **qué chats** se devuelven,
no los mensajes incluidos en cada chat. Cada chat devuelto sigue incluyendo sus
`messages_per_chat` mensajes más recientes (1 de forma predeterminada, hasta
200\), sin importar `since`.

Para sincronizar mensajes de forma fiable:

* Elimina duplicados por el `id` del mensaje, o
* Obtén el hilo de cada chat modificado en
  `GET /api/v1/chats/{chat_id}/messages`.

## `403 plan_limit_rest_api`

```json theme={null}
{ "code": "plan_limit_rest_api", "detail": "The REST API is not included in your plan. Upgrade to use API tokens." }
```

El acceso a la API REST con tokens de API depende del plan del negocio. El
servidor MCP no está sujeto a esta verificación: si tu plan no incluye la API
REST, puedes conectar igualmente un cliente de IA mediante MCP con OAuth.
Consulta [MCP](/es/api-reference/mcp).

## Tokens de acceso personal vs. claves de API del negocio

| | Token de acceso personal | Clave de API del negocio |
| - | - | - |
| Prefijo | `izap_pat_` | `izap_sk_` |
| Actúa como | Tú, con los permisos de tu rol | Un negocio |
| Dónde funciona | En cualquier endpoint en el que funcione tu login | Solo en los endpoints que aceptan claves de negocio (por ejemplo, chats y menús) |

* Crea tokens de acceso personal en el Dashboard: avatar → **Tu configuración**
  → **Claves API**. La pestaña solo aparece cuando el plan incluye la API REST.
* El token se muestra **una sola vez**, al crearlo. Guárdalo de inmediato.
* Los scopes son opcionales. Un token sin scopes tiene el acceso completo de tu
  rol; restríngelo con scopes como `chat:read`.
* Los endpoints de la biblioteca de medios
  (`/api/v1/businesses/library/images` y
  `/api/v1/businesses/library/documents`) requieren una credencial de usuario:
  un JWT o un token de acceso personal. Una clave de API del negocio recibe
  `401` en ellos.

## Un mensaje aparece como enviado, pero nunca llega

Meta acepta un mensaje libre enviado fuera de la ventana de atención de 24
horas, devuelve un id de mensaje y lo rechaza **después**, en el estado de
entrega. Tu llamada de envío tiene éxito; el fallo aparece más tarde.

* Revisa el estado de entrega con la herramienta MCP
  `get_whatsapp_message_status`, o en el mensaje dentro de la conversación.
* Para (re)abrir una conversación, envía una plantilla aprobada: MCP
  `send_whatsapp_template_message`, o REST
  `POST /api/v1/chats/{chat_id}/messages/template`. La ventana nunca bloquea el
  envío de plantillas.

Códigos de error de Meta comunes en el estado de entrega:

| Código | Significado |
| - | - |
| `131047` | La ventana de 24 horas está cerrada. Envía una plantilla aprobada. |
| `131026` | No se pudo entregar el mensaje; por ejemplo, porque el número no tiene WhatsApp. |
| `131049` | Meta retuvo un mensaje de marketing para proteger la experiencia del destinatario. Inténtalo más tarde. |
| `132000`–`132015` | Un problema con la propia plantilla (parámetros, estado o formato). |

## No puedes leer los archivos que envió un cliente

`get_chat_messages` devuelve los metadatos del archivo (nombre, tipo, id del
mensaje), pero el campo `media_url` no es un enlace de descarga público. Usa la
herramienta MCP `download_media` con el mensaje para obtener el archivo.

## Los chats de grupo no aparecen

La WhatsApp Business Platform solo entrega conversaciones individuales a los
proveedores. Los grupos, Comunidades y Canales no están disponibles a través de
iZap.

## El inicio de sesión del MCP falla o usa la cuenta equivocada

La página de inicio de sesión de OAuth acepta tu correo y contraseña de iZap, o
Google. Si tienes más de una cuenta de Google en el navegador, asegúrate de
elegir la que pertenece al negocio. Si la conexión sigue fallando, quita el
conector de tu cliente de IA y vuelve a agregarlo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.