> ## 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.
# Analytics MCP
> Conecta un cliente de IA o tu propio código al servidor MCP de iZap.
El **servidor MCP de iZap** permite que un agente de IA opere tu negocio de
WhatsApp de punta a punta, no solo enviar un mensaje. iZap es un BSP oficial de
WhatsApp que también controla la capa de aplicación (CRM, chatbots, pedidos,
analítica), y este servidor expone esa capa a cualquier agente mediante
**Streamable HTTP** en `{origin}/mcp`: consulta analítica, gestiona tus
asistentes de IA y envía mensajes y transmisiones. La misma lógica de negocio y
la misma autenticación que la API REST.
Cada herramienta está limitada a tu negocio mediante OAuth y lleva indicaciones
de solo lectura / destructiva, para que el agente sepa qué es seguro llamar
antes de hacerlo. Los títulos y las descripciones están disponibles en inglés y
portugués. Conecta Claude, ChatGPT o Cursor con un clic.
Cómo se compara iZap con las APIs solo de transporte (Twilio, Cloud API,
360dialog) y con las bandejas de entrada sin código, y cuándo conviene cada
una.
| Entorno | URL del MCP |
| - | - |
| Producción | `https://api.izap.ai/mcp` |
| Staging | `https://api-staging.izap.ai/mcp` |
## Conecta
La autenticación es OAuth 2.0 (los clientes interactivos la inician
automáticamente) o un JWT Bearer para código de servidor a servidor. Regístralo
como servidor MCP HTTP remoto:
```json theme={null}
{
"mcpServers": {
"izap": {
"type": "http",
"url": "https://api.izap.ai/mcp",
"headers": { "Authorization": "Bearer ${IZAP_TOKEN}" }
}
}
}
```
## Agrégalo a tu cliente de IA
Apunta cualquier cliente compatible con MCP a la URL de arriba; los clientes
interactivos hacen el login OAuth por ti.
**Con un clic:** abre [**Agregar iZap a Cursor**](cursor://anysphere.cursor-deeplink/mcp/install?name=izap\&config=eyJ1cmwiOiJodHRwczovL2FwaS5pemFwLmFpL21jcCJ9) y confirma la instalación, o pega este enlace en tu navegador:
```
cursor://anysphere.cursor-deeplink/mcp/install?name=izap&config=eyJ1cmwiOiJodHRwczovL2FwaS5pemFwLmFpL21jcCJ9
```
**Manual**: agrégalo a `~/.cursor/mcp.json` (global) o a `.cursor/mcp.json` (por proyecto):
```json theme={null}
{ "mcpServers": { "izap": { "url": "https://api.izap.ai/mcp" } } }
```
En claude.ai, ve a **Settings → Connectors → Add custom connector**, pega
`https://api.izap.ai/mcp` y completa el login OAuth. Funciona en Pro, Max,
Team y Enterprise.
Activa **Settings → Connectors → Advanced → Developer mode**, luego
**Add custom connector** y pega `https://api.izap.ai/mcp`.
Las cuentas individuales Plus/Pro reciben solo las herramientas de lectura. Las herramientas de WhatsApp / transmisiones (escritura) requieren un workspace Business, Enterprise o Edu.
```bash theme={null}
codex mcp add izap --url https://api.izap.ai/mcp
```
O agrégalo a `~/.codex/config.toml`:
```toml theme={null}
[mcp_servers.izap]
url = "https://api.izap.ai/mcp"
```
Verifica con `/mcp` dentro de Codex.
Ve a **Settings → Connectors → + Add Connectors → Custom MCP → Import by JSON**
y pega:
```json theme={null}
{ "izap": { "url": "https://api.izap.ai/mcp" } }
```
O usa **Direct Configuration** con el transporte *Streamable HTTP* y la URL
`https://api.izap.ai/mcp`.
**Cue**, la app de agente personal de Manus, usa el mismo servidor: agrega un
servidor MCP personalizado con la URL `https://api.izap.ai/mcp`.
**grok.com:** ve a [grok.com/connectors](https://grok.com/connectors), haz clic en
**New Connector → Custom**, pega `https://api.izap.ai/mcp` y completa el inicio de sesión.
**Grok Bot:** ve a **Settings → Plugins**, agrega un conector personalizado y pega
`https://api.izap.ai/mcp`.
Cambia el host por la URL de staging (`https://api-staging.izap.ai/mcp`) para hacer pruebas en staging.
## Catálogo de herramientas
Todas las herramientas aceptan un `business_id` (UUID) opcional; omítelo para
usar tu primer negocio. Las herramientas de solo lectura se pueden llamar
libremente; las marcadas como **escritura** crean, cambian o envían algo.
### Analítica (solo lectura)
| Herramienta | Propósito |
| - | - |
| `get_message_stats` | Conteo de chats / mensajes / personas únicas de una fecha (el nombre antiguo `get_today_message_stats` todavía se acepta, pero ya no aparece en la lista) |
| `get_assistant_ratio` | Proporción de mensajes de la IA frente a los humanos en una fecha (el nombre antiguo `get_today_assistant_ratio` todavía se acepta, pero ya no aparece en la lista) |
| `get_conversation_duration` | Duración media/mínima/máxima de las conversaciones de una fecha |
| `get_conversation_breakdown` | Desglose por conversación de una fecha |
| `search_messages` | Búsqueda por palabra clave en una fecha o un rango de fechas (el nombre antiguo `search_today_messages` todavía se acepta, pero ya no aparece en la lista) |
### Asistentes de IA
| Herramienta | Propósito |
| - | - |
| `list_connected_assistants` | Listar los asistentes de IA de la cuenta |
| `get_assistant_instructions` | Leer el prompt y las instrucciones de un asistente |
| `create_ai_assistant` | Crear un nuevo asistente **(escritura)** |
| `update_ai_assistant_instructions` | Actualizar el prompt o las instrucciones de un asistente **(escritura)** |
| `update_assistant_settings` | Actualizar la configuración de un asistente: activo/pausado, nombre, modelo, idioma, tono, saludos, respuesta fuera de horario **(escritura)** |
### Contactos y mensajería de WhatsApp
| Herramienta | Propósito |
| - | - |
| `list_contacts` | Listar los contactos de la cuenta |
| `list_chats` | Listar las conversaciones de WhatsApp del negocio |
| `get_chat_messages` | Leer los mensajes de una conversación, incluidos los metadatos de archivos |
| `download_media` | Descargar una foto, un audio o un documento que envió un cliente |
| `get_whatsapp_message_status` | Revisar el estado de entrega de un mensaje saliente y el código de error de Meta |
| `connect_whatsapp_number` | Obtener un enlace válido por una hora al flujo oficial de Meta para conectar un número de WhatsApp **(escritura)** |
| `get_whatsapp_connection_status` | Diagnosticar la conexión de WhatsApp: número, id de la WABA, registro, salud del webhook, sincronización del historial y el último error de Meta en lenguaje sencillo |
| `list_whatsapp_templates` | Listar las plantillas de mensajes de WhatsApp aprobadas |
| `create_whatsapp_template` | Crear una plantilla y enviarla a Meta para su aprobación **(escritura)** |
| `get_whatsapp_template_status` | Revisar el estado de aprobación de una plantilla creada y el motivo del rechazo |
| `send_whatsapp_message` | Enviar un mensaje de texto de WhatsApp **(escritura)** |
| `send_whatsapp_template_message` | Enviar una plantilla de mensaje de WhatsApp aprobada **(escritura)** |
### Biblioteca de medios
| Herramienta | Propósito |
| - | - |
| `list_library_images` | Listar la biblioteca de imágenes del negocio |
| `upload_library_image` | Agregar a la biblioteca una imagen codificada en base64 **(escritura)** |
| `delete_library_image` | Eliminar de forma permanente una imagen de la biblioteca **(escritura)** |
| `list_library_documents` | Listar los documentos y videos del negocio (PDF, DOCX, MP4) |
| `upload_library_document` | Agregar un documento o video codificado en base64 **(escritura)** |
| `delete_library_document` | Eliminar de forma permanente un documento de la biblioteca **(escritura)** |
### Transmisiones
| Herramienta | Propósito |
| - | - |
| `create_transmission_preview` | Crear la vista previa de una transmisión (audiencia + contenido) **(escritura)** |
| `confirm_transmission` | Enviar una transmisión con vista previa **(escritura)** |
| `list_transmissions` | Listar las transmisiones |
| `get_transmission_status` | Revisar el estado de entrega de una transmisión |
## Notas
* Las **fechas** son cadenas ISO-8601 (p. ej., `2026-04-15`); la **zona
horaria** es un nombre IANA (p. ej., `America/Sao_Paulo`).
* `search_messages` (y su nombre antiguo `search_today_messages`) tiene un
límite de uso por usuario por día.
* `create_whatsapp_template` responde en cuanto Meta acepta la plantilla para
revisión; la aprobación es asíncrona, así que consulta
`get_whatsapp_template_status` para conocer el resultado. Una plantilla solo
aparece en `list_whatsapp_templates` cuando Meta ya la tiene: esa herramienta
lee el catálogo de Meta, no los borradores locales.
* `send_whatsapp_template_message` necesita un archivo para una plantilla
aprobada con encabezado multimedia (documento, imagen o video), indicado
exactamente de una de estas formas:
* `header_media_image_id`: una imagen que ya está en la biblioteca de medios,
obtenida de `upload_library_image` o `list_library_images`. Es la opción
preferida para cualquier archivo reutilizado: iZap lo lee directamente del
almacenamiento, así que nada expira y no interviene ninguna URL.
* `header_media_document_id`: lo mismo para un documento o video, obtenido de
`upload_library_document` o `list_library_documents`. Su `header_kind`
(`document` o `video`) indica con qué formato de encabezado de plantilla
encaja.
* `header_media_url`: una URL `https://` accesible públicamente que iZap
descarga.
* `header_media_base64`: los bytes en sí, para un archivo puntual. No se
guarda en la biblioteca; llama primero a `upload_library_image` si debe ser
reutilizable. El tipo se detecta a partir del contenido, así que JPEG, PNG,
PDF, MP4 y 3GPP funcionan, y un documento de texto u Office necesita
`header_media_url`.
Agrega `header_media_filename` para controlar el nombre con el que el
destinatario ve un documento. El archivo puede ser distinto en cada envío;
solo el *formato* del encabezado lo fija la plantilla aprobada. Los documentos
aceptan PDF, texto plano, Word, Excel y PowerPoint de hasta 100 MB; las
imágenes aceptan JPEG/PNG de hasta 5 MB y los videos MP4/3GPP de hasta 16 MB.
Pasar un encabezado para una plantilla sin encabezado multimedia —u omitirlo
para una que sí lo tiene— falla antes de enviar nada.
* La biblioteca de medios guarda GIF y WebP, que WhatsApp **no** acepta como
imagen de encabezado de plantilla. `list_library_images` indica
`usable_as_template_header` para cada imagen, así que puedes elegir una válida
en lugar de descubrirlo al enviar.
* Las plantillas con encabezado multimedia deben crearse en el WhatsApp Manager
de Meta; `create_whatsapp_template` todavía no puede enviarlas.
* Los errores del servidor aparecen como errores de herramienta MCP
(`isError: true`) con el mensaje `Error : `; un `401`
significa que debes renovar el token.
Obtén un token y luego usa el SDK de MCP para Python o TypeScript para llamar a
estas herramientas desde tu propia aplicación o agente.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.