#crm #sales-pipeline #messaging #whatsapp

Volkern MCP Server

Automate Volkern CRM operations including lead management, appointment scheduling, task tracking, service catalog, WhatsApp messaging, sales pipeline, quotations, and contracts. Requires API key authentication.

DeXpertmx@dexpertmx

Install

openclaw skills install @dexpertmx/volkern-skill

Volkern CRM Automation

Automate CRM operations including lead lifecycle management, appointment scheduling with availability checks, task creation, service catalog queries, WhatsApp communication, sales pipeline management, quotation/proposal generation, and contract handling through Volkern's REST API.

Prerequisites

Volkern API Key with appropriate permissions
Base URL: https://volkern.app/api (or your custom domain)
All requests require Authorization: Bearer {API_KEY} header
Timestamps must be in ISO 8601 format (UTC): yyyy-MM-ddTHH:mm:ss.fffZ

Setup

Log into Volkern dashboard
Navigate to Configuración → API Keys
Create a new API key with required permissions:
- leads:read, leads:write for lead management
- citas:read, citas:write for appointments
- servicios:read for service catalog
- mensajes:write for WhatsApp messaging
Copy the API key (shown only once)
Use the key in the Authorization header for all requests

Core Workflows

1. Lead Management

When to use: Create, update, search, or manage leads in the CRM

Tool sequence:

VOLKERN_LIST_LEADS - Search and filter existing leads [Optional]
VOLKERN_GET_LEAD - Get detailed lead information by ID [Optional]
VOLKERN_CREATE_LEAD - Create a new lead [Required for new leads]
VOLKERN_UPDATE_LEAD - Update lead properties [Required for updates]

Key parameters:

Endpoint	Method	Parameters
`/api/leads`	GET	`estado`, `canal`, `etiqueta`, `search`, `page`, `limit`
`/api/leads/{id}`	GET	`id` (path)
`/api/leads`	POST	`nombre`*, `email`, `telefono`, `empresa`, `canal`, `estado`, `etiquetas`, `notas`, `contextoProyecto`
`/api/leads/{id}`	PATCH	Any lead field to update

Lead estados (stages):

nuevo - New lead, not contacted
contactado - Initial contact made
calificado - Qualified lead
negociacion - In negotiation
cliente - Converted to customer
perdido - Lost opportunity

Pitfalls:

nombre is the only required field for lead creation
Email is validated for format but not uniqueness (upsert behavior: existing email updates the lead)
canal should match predefined values: web, referido, whatsapp, telefono, email, otro
etiquetas is an array of strings: ["vip", "urgente"]

2. Appointment Scheduling

When to use: Book appointments, check availability, manage calendar

Tool sequence:

VOLKERN_LIST_SERVICIOS - Get available services with durations [Prerequisite]
VOLKERN_CHECK_DISPONIBILIDAD - Query available time slots [Required]
VOLKERN_CREATE_CITA - Book the appointment [Required]
VOLKERN_LIST_CITAS - List existing appointments [Optional]
VOLKERN_UPDATE_CITA - Reschedule or modify [Optional]
VOLKERN_CANCEL_CITA - Cancel appointment [Optional]

Key parameters:

Endpoint	Method	Parameters
`/api/citas/disponibilidad`	GET	`fecha`* (YYYY-MM-DD), `duracion` (minutes, default 60)
`/api/citas`	GET	`estado`, `tipo`, `fecha`, `fechaInicio`, `fechaFin`
`/api/citas`	POST	`leadId`, `fechaHora`, `tipo`, `titulo`, `descripcion`, `duracion`, `servicioId`
`/api/citas/{id}`	PATCH	`fechaHora`, `estado`, `duracion`, `descripcion`
`/api/citas/accion`	POST	`citaId`, `accion` (`confirmar`\|`cancelar`\|`reprogramar`)

Availability response structure:

json

{
  "fecha": "2026-02-10",
  "dia": "lunes",
  "diaActivo": true,
  "horarioLaboral": {
    "rangos": [{"inicio": "09:00", "fin": "13:00"}, {"inicio": "15:00", "fin": "18:00"}],
    "resumen": "09:00-13:00, 15:00-18:00"
  },
  "disponibles": {
    "total": 12,
    "slots": ["2026-02-10T09:00:00.000Z", "2026-02-10T09:30:00.000Z", ...]
  },
  "ocupados": {
    "total": 2,
    "slots": [{"hora": "...", "cita": {"id": "...", "titulo": "..."}}]
  }
}

Cita tipos:

reunion - General meeting (default)
servicio - Service appointment (requires servicioId)
llamada - Phone call
otro - Other

Cita estados:

Pendiente - Awaiting confirmation
Confirmada - Confirmed by client
Completada - Meeting completed
Cancelada - Cancelled
Pagada - Paid (for paid services)

Pitfalls:

Always check diaActivo before attempting to book - inactive days return 0 slots
duracion must be an integer (minutes), not a string
fechaHora must be ISO 8601 UTC format
Booking on an occupied slot returns 409 Conflict with suggested alternatives
Weekend availability depends on tenant configuration in Configuración → Horarios

3. Task Management

When to use: Create follow-up tasks, reminders, or activities for leads

Tool sequence:

VOLKERN_GET_LEAD - Verify lead exists [Prerequisite]
VOLKERN_CREATE_TASK - Create task for the lead [Required]
VOLKERN_LIST_TASKS - Get lead's pending tasks [Optional]
VOLKERN_COMPLETE_TASK - Mark task as done [Optional]

Key parameters:

Endpoint	Method	Parameters
`/api/leads/{leadId}/tasks`	GET	`leadId` (path)
`/api/leads/{leadId}/tasks`	POST	`tipo`, `titulo`, `fechaVencimiento`*, `descripcion`, `asignadoA`
`/api/tasks/{taskId}`	PATCH	`completada`, `fechaCompletado`

Task tipos:

llamada - Phone call to make
email - Email to send
reunion - Meeting to schedule
recordatorio - General reminder

Pitfalls:

tipo must be lowercase and one of the valid values
fechaVencimiento is required and must be a future date
Tasks are automatically associated with the tenant via the API key

4. Service Catalog

When to use: Query available services for booking or pricing information

Tool sequence:

VOLKERN_LIST_SERVICIOS - Get all services [Required]
VOLKERN_GET_SERVICIO - Get specific service details [Optional]

Key parameters:

Endpoint	Method	Parameters
`/api/servicios`	GET	`activo` (boolean)
`/api/servicios/{id}`	GET	`id` (path)

Service response structure:

json

{
  "id": "clxyz...",
  "nombre": "Consultoría Inicial",
  "descripcion": "Sesión de 60 minutos...",
  "duracionMinutos": 60,
  "precio": 150.00,
  "moneda": "EUR",
  "modalidad": "virtual",
  "activo": true
}

Modalidades:

presencial - In-person
virtual - Online/video call
hibrido - Hybrid (generates Google Meet link if connected)

Pitfalls:

Only activo: true services should be offered for booking
duracionMinutos determines the slot blocking duration
Prices are in the tenant's configured currency

5. WhatsApp Messaging

When to use: Send WhatsApp messages to leads via connected integration

Tool sequence:

VOLKERN_GET_LEAD - Get lead's phone number [Prerequisite]
VOLKERN_SEND_WHATSAPP - Send message [Required]
VOLKERN_LIST_CONVERSACIONES - View conversation history [Optional]

Key parameters:

Endpoint	Method	Parameters
`/api/mensajes/enviar`	POST	`leadId`, `mensaje`, `tipo`
`/api/mensajes/conversaciones`	GET	`leadId`, `page`, `limit`
`/api/mensajes/conversaciones/{id}`	GET	`id` (path)

Message tipos:

texto - Plain text message
imagen - Image with optional caption
documento - Document attachment

Pitfalls:

Requires active WhatsApp integration (Evolution API or Anytimebot)
Lead must have a valid telefono field with country code
Message delivery is async; check conversation history for status
Rate limits apply based on WhatsApp Business policies

6. Lead Interactions

When to use: Record calls, meetings, or other activities with leads

Tool sequence:

VOLKERN_GET_LEAD - Verify lead exists [Prerequisite]
VOLKERN_LIST_INTERACTIONS - View existing interactions [Optional]
VOLKERN_CREATE_INTERACTION - Log the interaction [Required]

Key parameters:

Endpoint	Method	Parameters
`/api/leads/{id}/interactions`	GET	`id` (path) - Returns all interactions for the lead
`/api/leads/{id}/interactions`	POST	`tipo`, `contenido`, `resultado`, `metadatos`

Interaction tipos:

llamada - Phone call
email - Email sent/received
whatsapp - WhatsApp message
reunion - Meeting held
nota - Internal note
otro - Other interaction type

Resultado values:

positivo - Positive outcome
neutro - Neutral
negativo - Negative outcome

Response structure:

json

{
  "success": true,
  "interaction": {
    "id": "clxyz...",
    "leadId": "clxyz...",
    "tipo": "llamada",
    "contenido": "Discussed pricing options...",
    "resultado": "positivo",
    "metadatos": { "duracion": "15min" },
    "fechaCreacion": "2026-02-09T10:00:00Z",
    "creador": { "id": "...", "name": "John", "email": "john@example.com" }
  }
}

Pitfalls:

tipo must be lowercase
Interactions automatically update lead's fechaUltimaActividad
Triggers interaccion_creada automation event

7. Lead Notes

When to use: Add internal notes or observations about leads

Tool sequence:

VOLKERN_GET_LEAD - Verify lead exists [Prerequisite]
VOLKERN_LIST_NOTES - View existing notes [Optional]
VOLKERN_CREATE_NOTE - Add a new note [Required]

Key parameters:

Endpoint	Method	Parameters
`/api/leads/{id}/notes`	GET	`id` (path) - Returns all notes for the lead
`/api/leads/{id}/notes`	POST	`contenido`*, `titulo` (optional)

Response structure:

json

{
  "success": true,
  "note": {
    "id": "clxyz...",
    "leadId": "clxyz...",
    "contenido": "**Important**\n\nClient prefers morning calls...",
    "fechaCreacion": "2026-02-09T10:00:00Z",
    "creador": { "id": "...", "name": "John", "email": "john@example.com" }
  }
}

Pitfalls:

If titulo is provided, it's prepended to contenido as bold markdown
Notes automatically update lead's fechaUltimaActividad
Triggers nota_creada automation event

8. Contacts & Companies

When to use: Manage business contacts (persons) and companies separately from leads

Tool sequence:

VOLKERN_LIST_CONTACTS - Search and filter contacts [Optional]
VOLKERN_GET_CONTACT - Get detailed contact information [Optional]
VOLKERN_CREATE_CONTACT - Create a new contact or company [Required for new]
VOLKERN_UPDATE_CONTACT - Update contact properties [Required for updates]

Key parameters:

Endpoint	Method	Parameters
`/api/contacts`	GET	`tipo` (person/company), `search`, `page`, `limit`
`/api/contacts/{id}`	GET	`id` (path)
`/api/contacts`	POST	`nombre`*, `email`, `telefono`, `tipo`, `cargo`, `ubicacion`, `companyId`, `linkedin`, `notas`, `tags`
`/api/contacts/{id}`	PATCH	Any contact field to update

Contact tipos:

person - Individual person (default)
company - Business/organization

Response structure:

json

{
  "id": "clxyz...",
  "nombre": "María García",
  "email": "maria@empresa.com",
  "telefono": "+34612345678",
  "tipo": "person",
  "cargo": "Directora de Marketing",
  "ubicacion": "Madrid, España",
  "company": { "id": "...", "nombre": "Empresa S.L." },
  "linkedin": "https://linkedin.com/in/mariagarcia",
  "tags": ["VIP", "Decision Maker"],
  "deals": [{ "id": "...", "titulo": "..." }],
  "fechaCreacion": "2026-02-09T10:00:00Z"
}

Pitfalls:

nombre is the only required field
companyId links a person to their company
Companies can have multiple associated contacts
Use tipo=company to list only companies

9. Sales Pipeline (Deals)

When to use: Manage sales opportunities through pipeline stages

Tool sequence:

VOLKERN_LIST_PIPELINE_STAGES - Get configured stages [Prerequisite]
VOLKERN_LIST_DEALS - Search and filter deals [Optional]
VOLKERN_CREATE_DEAL - Create a new opportunity [Required for new]
VOLKERN_UPDATE_DEAL - Move stage, update value, close deal [Required for updates]
VOLKERN_GET_SALES_FORECAST - Get pipeline analytics [Optional]

Key parameters:

Endpoint	Method	Parameters
`/api/pipeline/stages`	GET	-
`/api/deals`	GET	`etapa`, `estado`, `prioridad`, `search`, `page`, `limit`
`/api/deals/{id}`	GET	`id` (path)
`/api/deals`	POST	`titulo`*, `valor`, `moneda`, `etapa`, `prioridad`, `probabilidad`, `fechaEstimadaCierre`, `leadId`, `contactId`, `companyId`, `descripcion`
`/api/deals/{id}`	PATCH	Any deal field to update
`/api/deals/forecast`	GET	`periodo` (mes/trimestre/año)

Deal estados:

abierto - Active opportunity (default)
ganado - Won deal
perdido - Lost deal

Deal prioridades:

baja - Low priority
media - Medium priority
alta - High priority

Default pipeline stages (probability in %):

Stage	Probability
Calificación	10%
Contacto Inicial	25%
Propuesta	50%
Negociación	75%
Cierre	90%
Ganado	100%
Perdido	0%

Forecast response structure:

json

{
  "basicForecast": { "total": 125000, "ponderado": 45000 },
  "adjustedForecast": { "total": 42000, "confianza": 0.85 },
  "conversionRates": { "Calificación": { "teorica": 10, "real": 8.5 } },
  "cycleTime": { "promedioDias": 45 },
  "projection6Months": [{ "mes": "Feb 2026", "estimado": 15000 }],
  "historicalSales": [{ "mes": "Jan 2026", "total": 12000 }],
  "funnel": [{ "etapa": "Calificación", "cantidad": 10, "valor": 50000 }],
  "topDeals": [{ "id": "...", "titulo": "...", "valorPonderado": 15000 }]
}

Pitfalls:

titulo is the only required field
etapa must match exact stage name (case-sensitive)
probabilidad auto-updates when changing etapa
Moving to "Ganado" auto-sets estado: ganado and probabilidad: 100
Moving to "Perdido" auto-sets estado: perdido and probabilidad: 0

10. Quotations (Cotizaciones)

When to use: Create and send price quotes/proposals to clients

Tool sequence:

VOLKERN_GET_LEAD or VOLKERN_GET_DEAL - Get client info [Prerequisite]
VOLKERN_LIST_COTIZACIONES - View existing quotes [Optional]
VOLKERN_CREATE_COTIZACION - Create new quote with items [Required]
VOLKERN_UPDATE_COTIZACION - Edit quote (only in borrador status) [Optional]
VOLKERN_SEND_COTIZACION - Email quote to client [Optional]

Key parameters:

Endpoint	Method	Parameters
`/api/cotizaciones`	GET	`estado`, `search`, `page`, `limit`
`/api/cotizaciones/{id}`	GET	`id` (path)
`/api/cotizaciones`	POST	`leadId`, `dealId`, `validezDias`, `notas`, `items`*
`/api/cotizaciones/{id}`	PATCH	`estado`, `validezDias`, `notas`, `items`
`/api/cotizaciones/{id}/send`	POST	`mensaje` (optional email text)

Item structure:

json

{
  "concepto": "Consultoría inicial",
  "cantidad": 2,
  "precioUnitario": 150.00,
  "descuento": 10
}

Cotización estados:

borrador - Draft (editable)
enviada - Sent to client
aceptada - Accepted by client
rechazada - Rejected
expirada - Validity expired

Response structure:

json

{
  "id": "clxyz...",
  "numero": "COT-2026-0001",
  "estado": "borrador",
  "subtotal": 270.00,
  "iva": 56.70,
  "total": 326.70,
  "validezDias": 30,
  "fechaExpiracion": "2026-03-11",
  "items": [...],
  "lead": { "nombre": "...", "email": "..." },
  "urlPublica": "https://volkern.app/cotizacion/abc123"
}

Pitfalls:

items array is required with at least one item
Only borrador status quotes can be edited
Quote number is auto-generated (COT-YYYY-####)
validezDias defaults to 30 if not specified
Client can accept quote via public URL
Accepted quotes can be converted to contracts

11. Contracts (Contratos)

When to use: Create formal contracts from accepted quotes or manually

Tool sequence:

VOLKERN_LIST_COTIZACIONES - Find accepted quote [Optional]
VOLKERN_CREATE_CONTRATO_FROM_COTIZACION - Convert quote to contract [Option A]
VOLKERN_CREATE_CONTRATO - Create contract manually [Option B]
VOLKERN_LIST_CONTRATOS - View existing contracts [Optional]
VOLKERN_SEND_CONTRATO - Send for client signature [Required]

Key parameters:

Endpoint	Method	Parameters
`/api/contratos`	GET	`estado`, `tipo`, `search`, `page`, `limit`
`/api/contratos/{id}`	GET	`id` (path)
`/api/contratos`	POST	`titulo`*, `tipo`, `leadId`, `dealId`, `cotizacionId`, `fechaInicio`, `fechaFin`, `metodoPago`, `clausulas`, `items`
`/api/contratos/from-cotizacion/{cotizacionId}`	POST	`fechaInicio`, `fechaFin`, `metodoPago`, `clausulas`
`/api/contratos/{id}/send`	POST	`mensaje` (optional email text)

Contrato tipos:

servicios - Service agreement
productos - Product sale
suscripcion - Subscription
proyecto - Project-based
otro - Other

Contrato estados:

borrador - Draft
enviado - Sent for signature
firmado_cliente - Signed by client
firmado_empresa - Signed by company
activo - Both signatures, active
completado - Fulfilled
cancelado - Cancelled

Método de pago:

unico - Single payment
mensual - Monthly payments
trimestral - Quarterly payments
anual - Annual payments

Response structure:

json

{
  "id": "clxyz...",
  "numero": "CONT-2026-0001",
  "titulo": "Contrato de Servicios",
  "tipo": "servicios",
  "estado": "enviado",
  "total": 12000.00,
  "fechaInicio": "2026-02-15",
  "fechaFin": "2027-02-14",
  "metodoPago": "mensual",
  "firmadoPorCliente": false,
  "firmadoPorEmpresa": false,
  "items": [...],
  "pagos": [...],
  "urlPublica": "https://volkern.app/contrato/xyz789"
}

Pitfalls:

Contract number is auto-generated (CONT-YYYY-####)
Creating from cotización copies items automatically
Client signs via public URL (no login required)
Payment schedule is auto-generated based on metodoPago
activo status requires both signatures
Digital signatures include timestamp and IP

Common Patterns

ID Resolution

Volkern uses CUID format for all entity IDs:

Example: clxyz123abc456def789
Always retrieve IDs from list/create responses
Never construct IDs manually

Pagination

List endpoints support pagination:

text

GET /api/leads?page=1&limit=50

Default limit: 50
Maximum limit: 100
Response includes total count for pagination UI

Time Handling

All timestamps are in UTC
Format: yyyy-MM-ddTHH:mm:ss.fffZ
Availability queries use date only: YYYY-MM-DD
Frontend displays in tenant's configured timezone

Error Handling

Standard HTTP status codes:

200 - Success
201 - Created
400 - Bad Request (validation error)
401 - Unauthorized (invalid/missing API key)
404 - Not Found
409 - Conflict (e.g., scheduling conflict)
500 - Server Error

Error response format:

json

{
  "error": "Descriptive error message",
  "details": "Additional context",
  "hint": "How to fix the issue"
}

Quick Reference

Task	Endpoint	Method	Key Params
LEADS
List leads	`/api/leads`	GET	`estado`, `search`, `page`
Get lead	`/api/leads/{id}`	GET	`id`
Create lead	`/api/leads`	POST	`nombre`*, `email`, `telefono`
Update lead	`/api/leads/{id}`	PATCH	Any field
APPOINTMENTS
Check availability	`/api/citas/disponibilidad`	GET	`fecha`*, `duracion`
List appointments	`/api/citas`	GET	`estado`, `fecha`
Create appointment	`/api/citas`	POST	`leadId`, `fechaHora`, `tipo`
Update appointment	`/api/citas/{id}`	PATCH	`estado`, `fechaHora`
Confirm/Cancel	`/api/citas/accion`	POST	`citaId`, `accion`
SERVICES
List services	`/api/servicios`	GET	`activo`
Get service	`/api/servicios/{id}`	GET	`id`
TASKS
Create task	`/api/leads/{id}/tasks`	POST	`tipo`, `titulo`, `fechaVencimiento`*
List tasks	`/api/leads/{id}/tasks`	GET	-
Complete task	`/api/tasks/{id}`	PATCH	`completada: true`
MESSAGING
Send WhatsApp	`/api/mensajes/enviar`	POST	`leadId`, `mensaje`
List conversations	`/api/mensajes/conversaciones`	GET	`leadId`
INTERACTIONS
List interactions	`/api/leads/{id}/interactions`	GET	-
Create interaction	`/api/leads/{id}/interactions`	POST	`tipo`, `contenido`, `resultado`
NOTES
List notes	`/api/leads/{id}/notes`	GET	-
Add note	`/api/leads/{id}/notes`	POST	`contenido`*, `titulo`
CONTACTS
List contacts	`/api/contacts`	GET	`tipo`, `search`, `page`
Get contact	`/api/contacts/{id}`	GET	`id`
Create contact	`/api/contacts`	POST	`nombre`*, `email`, `tipo`
Update contact	`/api/contacts/{id}`	PATCH	Any field
DEALS
List pipeline stages	`/api/pipeline/stages`	GET	-
List deals	`/api/deals`	GET	`etapa`, `estado`, `search`
Get deal	`/api/deals/{id}`	GET	`id`
Create deal	`/api/deals`	POST	`titulo`*, `valor`, `etapa`
Update deal	`/api/deals/{id}`	PATCH	`etapa`, `estado`, `valor`
Sales forecast	`/api/deals/forecast`	GET	`periodo`
QUOTATIONS
List quotes	`/api/cotizaciones`	GET	`estado`, `search`
Get quote	`/api/cotizaciones/{id}`	GET	`id`
Create quote	`/api/cotizaciones`	POST	`items`*, `leadId`, `dealId`
Update quote	`/api/cotizaciones/{id}`	PATCH	`items`, `notas`
Send quote	`/api/cotizaciones/{id}/send`	POST	`mensaje`
CONTRACTS
List contracts	`/api/contratos`	GET	`estado`, `tipo`, `search`
Get contract	`/api/contratos/{id}`	GET	`id`
Create contract	`/api/contratos`	POST	`titulo`*, `tipo`, `items`
Create from quote	`/api/contratos/from-cotizacion/{id}`	POST	`fechaInicio`, `metodoPago`
Send contract	`/api/contratos/{id}/send`	POST	`mensaje`

* = Required field

Known Pitfalls

Authentication

API keys are tenant-scoped; one key per organization
Keys can have granular permissions; check scope if getting 401/403
Never expose API keys in client-side code

Data Validation

Phone numbers should include country code: +34612345678
Email validation is strict; malformed emails are rejected
Dates in the past may be rejected for appointments

Scheduling Conflicts

The system validates overlapping appointments
Use disponibilidad endpoint before booking
409 responses include suggested alternative slots

WhatsApp Integration

Requires pre-configured integration (Evolution API)
First message to new number requires template approval
Media messages have size limits (16MB for images)

Rate Limits

Standard: 100 requests/minute per API key
Bulk operations: 10 requests/minute
WhatsApp: Subject to Meta's messaging limits

Volkern MCP Server

Install

Volkern CRM Automation

Prerequisites

Setup

Core Workflows

1. Lead Management

2. Appointment Scheduling

3. Task Management

4. Service Catalog

5. WhatsApp Messaging

6. Lead Interactions

7. Lead Notes

8. Contacts & Companies

9. Sales Pipeline (Deals)

10. Quotations (Cotizaciones)

11. Contracts (Contratos)

Common Patterns

ID Resolution

Pagination

Time Handling

Error Handling

Quick Reference

Known Pitfalls

Authentication

Data Validation

Scheduling Conflicts

WhatsApp Integration

Rate Limits

Related skills