Integración MCP de Summit Notify

Summit Notify expone un endpoint Model Context Protocol sobre HTTP streamable para que agentes de Summit AI puedan listar, leer y responder conversaciones de WhatsApp.

URL y autenticación

POST /mcp
Authorization: Bearer SUMMIT_NOTIFY_API_KEY

El endpoint requiere una API key de Summit Notify. No acepta access tokens OpenID Connect. Cada request debe incluir el header Authorization: Bearer <key>; no hay sesiones persistentes del lado del servidor.

Herramientas disponibles

list_conversations

Lista las conversaciones del tenant, más recientes primero.

Argumento	Tipo	Requerido	Descripción
window	string	No	open (ventana de 24 h abierta), closed o omitir para todas.
q	string	No	Substring del teléfono del cliente.
limit	number	No	1–100, default 25.
cursor	string	No	next_cursor de una llamada anterior.

Respuesta:

{
  "conversations": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "customer_phone": "+593999999999",
      "whatsapp_account_id": "11111111-1111-1111-1111-111111111111",
      "window_open": true,
      "service_window_expires_at": "2026-08-18T22:00:00Z",
      "updated_at": "2026-08-18T18:00:00Z"
    }
  ],
  "next_cursor": "ey..."
}

get_conversation

Devuelve el detalle de una conversación.

Argumento	Tipo	Requerido	Descripción
id	string	Sí	UUID de la conversación.

get_conversation_messages

Devuelve el historial de mensajes de una conversación, más recientes primero.

Argumento	Tipo	Requerido	Descripción
id	string	Sí	UUID de la conversación.
limit	number	No	1–500, default 100.

Respuesta:

{
  "messages": [
    {
      "id": "33333333-3333-3333-3333-333333333333",
      "direction": "inbound",
      "message_type": "text",
      "payload": { "body": "Hola" },
      "occurred_at": "2026-08-18T18:00:00Z"
    }
  ],
  "window_open": true,
  "service_window_expires_at": "2026-08-18T22:00:00Z",
  "updated_at": "2026-08-18T18:00:00Z"
}

reply_to_conversation

Encola una respuesta en la conversación.

Argumento	Tipo	Requerido	Descripción
id	string	Sí	UUID de la conversación.
message_type	string	No	text (default), image, video, audio, document, location.
text	string	Condicional	Cuerpo para text.
media_id	string	Condicional	ID de WhatsApp de un adjunto previamente subido.
media_url	string	Condicional	URL HTTPS pública de un adjunto.
caption	string	No	Pie para multimedia.
filename	string	No	Nombre de archivo para document.
latitude	number	Condicional	Requerido para location.
longitude	number	Condicional	Requerido para location.
location_name	string	No	Nombre del lugar.
address	string	No	Dirección del lugar.
fallback_template_id	string	No	UUID de plantilla aprobada; se usa si la ventana se cerró antes del envío.
fallback_parameters	string[]	No	Valores de parámetros de la plantilla, en orden.

Respuesta:

{
  "notification_id": "44444444-4444-4444-4444-444444444444",
  "status": "pending"
}

Reglas de negocio

Los tools comparten las mismas reglas que el panel de conversaciones y la API JSON de WhatsApp:

• Durante la ventana de servicio de 24 horas se permiten mensajes libres.
• Fuera de la ventana, reply_to_conversation solo acepta una respuesta si incluye fallback_template_id válido y aprobado; de lo contrario el tool responde con error.
• media_id y media_url son mutuamente excluyentes para tipos multimedia.
• La carga y descarga de archivos binarios no está disponible por MCP; usá los endpoints JSON para multimedia.

Errores

Los errores del protocolo MCP se devuelven como mensajes JSON-RPC de error. Los errores de negocio (ventana cerrada, conversación no encontrada, plantilla inválida) se devuelven como resultado de tool con isError: true y un mensaje de texto que el agente puede leer.

Situación	Resultado
Falta o es inválida la API key	JSON-RPC error 401.
UUID de conversación inválido	Tool error.
Conversación no encontrada	Tool error (404 lógico).
Ventana cerrada sin fallback	Tool error.
Plantilla fallback no aprobada	Tool error.
Error interno	JSON-RPC error 500.

Limitaciones

• Solo lectura y respuesta de conversaciones. No expone administración de cuentas, plantillas ni notificaciones generales.
• No soporta adjuntos binarios directamente; usá /api/v1/whatsapp-conversations/{id}/media-upload para subir y reply con media_id.
• El endpoint no establece sesiones persistentes: cada request requiere la API key.