Mosend
MosendDeveloper
Para agentes de IA

Construir con agentes de IA

Esta página está pensada para que un LLM (Claude, ChatGPT, Copilot, etc.) o un agente autónomo pueda generar integraciones correctas contra la API de Mosend sin adivinar. Todo lo de abajo es estable y verificable contra el spec.

Recursos machine-readable

OpenAPI 3

Spec completo: todos los endpoints, params, bodies y schemas. Ingerible por Postman, codegen, MCP, ChatGPT Actions.

llms.txt

Índice conciso (estándar llmstxt.org) de guías y módulos.

llms-full.txt

Corpus aplanado: todos los endpoints con sus params y campos, para pegar como contexto.

¿Construyendo un GPT/agente? Carga /openapi.json como tool/action y/llms-full.txt como contexto.

Instrucciones canónicas (system prompt)

Copia este bloque al system prompt de tu agente. Es la fuente de verdad de las reglas de la API.

Estás integrando la API de Mosend (Tech Provider de WhatsApp Business Cloud).

BASE URL: https://api.mosend.dev
AUTENTICACIÓN: header  X-Api-Key: mk_live_<prefix>.<secret>
  (alternativa: Authorization: Bearer <jwt> para sesiones interactivas)
MULTI-TENANCY: casi toda ruta es /organizations/{orgId}/...  — el orgId es obligatorio.
RESPUESTAS: todo viene envuelto en { "data": ... , "timestamp": ..., "requestId": ... }.
ERRORES: HTTP estándar; el cuerpo trae { statusCode, error, message }. 401 = auth; 403 = sin permiso/scope; 429 = rate limit.
IDEMPOTENCIA: los webhooks salientes NO traen un id de entrega; deduplica por el id del recurso dentro de "data" (p.ej. data.message.id). Los envíos NO son idempotentes; no reintentes a ciegas.
WEBHOOKS: el body llega como { type, organizationId, data, timestamp }; el tipo de evento también va en el header X-Mosend-Event y la firma en X-Mosend-Signature (HMAC SHA-256 del body crudo).
SCOPES: las API keys pueden restringirse a permisos y a números (phoneNumberIds). Si recibes 403 en un envío, el número puede estar fuera del scope de la key.
SPEC: la verdad de endpoints/params/bodies está en https://developer.mosend.dev/openapi.json — úsalo, no inventes campos.

Para enviar una plantilla: POST /organizations/{orgId}/messages con
  { phoneNumberId, to, type: "template", templateName (o templateId), templateLanguage, variables }.
Las plantillas con botón quick-reply/COPY_CODE requieren el component button en variables — ver la guía de plantillas.

BOT — AGENTES: CRUD en /organizations/{orgId}/bot/agents (name, systemPrompt, provider/model, enabledTools, enabledCapabilities, routeTags, knowledgeDocIds, phoneNumberIds, isDefault). Una routeTag pertenece a un solo agente (400 si choca). Rendimiento: GET .../bot/agents/stats?dias=N.
BOT — CONVERSACIÓN: PATCH /organizations/{orgId}/conversations/{id}/agent { agentId | null } fija o suelta el agente; POST .../conversations/{id}/devolver-al-bot reactiva el bot tras un handoff.
BOT — MEMORIA: fuentes en /organizations/{orgId}/bot/knowledge (archivo multipart), .../bot/knowledge/notes (texto) y .../bot/knowledge/url (página, syncEveryHours). Buscar: POST .../bot/knowledge/search { query, topK, tags, minSimilarity } → results[{ content, title, docId, similarity, porTexto }]. Vacíos: GET .../bot/knowledge/insights?dias=N.
TAREAS: GET/POST /organizations/{orgId}/tasks (scope=mine|team|all, status=pending|overdue|completed); PATCH .../tasks/{taskId}/claim y /complete { completed }. Tareas con origin "BOT" las crea el bot fuera de horario y se completan solas cuando un humano responde.

Reglas que un agente debe respetar

Auth y scope

Header X-Api-Key. Si la key tiene scopes/números restringidos, respeta el 403 — no es un bug, es la key acotada. Nunca pongas la key en la URL.

Idempotencia y reintentos

Los webhooks no traen un id de entrega: deduplica por el id del recurso en data (ej. data.message.id). No reintentes envíos de mensajes automáticamente: puedes duplicar conversaciones y costos. Reintenta solo 429/5xx con backoff.

No inventes el contrato

Antes de armar un request, valida el shape contra /openapi.json. Los campos, enums y obligatoriedad salen de ahí.

Superficies del bot y CRM

Además de mensajería, un agente puede operar el bot y el CRM de la organización. Cada guía trae ejemplos y el shape de las respuestas:

  • Agentes del bot — CRUD en /bot/agents, precedencia del enrutamiento, routeTags únicas, stats?dias=.
  • Memoria del bot — archivos, notas y URLs en /bot/knowledge; POST /bot/knowledge/search para buscar; insights para los vacíos.
  • Tareas — cola del equipo (scope=team), claim y complete; las de origin: BOT se cierran solas.
  • Handoff a humano — request-handoff, y por qué fuera de horario el bot crea una tarea en vez de traspasar; PATCH /conversations/{id}/agent para fijar el agente.

Empieza por aquí (humanos)