Cómo mover la etapa de un contacto con el conector de Waspy (sin pisar las otras etiquetas)
move_contact_stage deja una sola etiqueta etapa: y escribe funnelStage. El PATCH de /contacts reemplaza tags y customFields enteros. Ninguno de los dos le escribe al cliente.
Respuesta corta: la etapa manual de un contacto se cambia con la herramienta move_contact_stage del conector MCP, en https://api.waspytech.com/mcp, con el scope contacts:write. La etapa tiene que estar en el catálogo (nuevo, en_conversacion, esperando, ganado, perdido, salvo que la cuenta haya definido otras). La herramienta deja una sola etiqueta etapa:…, escribe funnelStage en los datos del contacto y no le manda un WhatsApp.
No hay un endpoint REST /api/v2/funnel. El PATCH /api/v2/contacts/:id puede imitar el resultado si reenviás la lista completa de etiquetas y el objeto completo de customFields. Si mandás solo la etapa, pisás el resto. Cómo se conecta Claude, Cursor, ChatGPT, Codex o Grok está en el conector. La guía publicada está en conectar el MCP.
La clave de API está en Scale (US$150 por mes) y Enterprise. Starter y Growth no la incluyen. Los planes están en Planes y el módulo, en la API.
Las dos cosas que se mezclan
| Etapa manual | Clasificación automática | |
|---|---|---|
| Qué es | La etiqueta etapa:ganado y el campo funnelStage | temperature: hot, warm, silent o cold |
| Quién la cambia | move_contact_stage, o un PATCH armado a mano | Waspy, según la actividad. Esta llamada no la toca |
| Cómo se lee | list_funnel_stages → catalog y usage | list_funnel_stages → classification, o get_metrics → contactsByTemperature |
| En el panel | La etiqueta etapa: | Muy activo, Activo, Silencioso, Frío |
temperature es null, el conteo de get_metrics lo agrupa como sin_clasificar. La habilidad seguimiento-de-leads del conector le pide al asistente que no confunda las dos. El texto de esa habilidad no mueve a nadie solo.
Listar antes de mover
list_funnel_stages no lleva argumentos y pide contacts:read. Devuelve tres listas:
catalog: las etapas válidas de esta cuenta.usage: cuántos contactos tienen cadafunnelStageya guardado (hasta 50 grupos).classification: el conteo portemperature.
list_tags pide el mismo scope y devuelve tags: cada tag y su count, de mayor a menor. Sin limit, el tope es 20. El máximo es 50. Ahí vas a ver etapa:ganado mezclada con vip o cm2026, porque para la base son etiquetas.
curl -sS -X POST https://api.waspytech.com/mcp \
-H "Authorization: Bearer $WASPY_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": { "name": "list_funnel_stages", "arguments": {} }
}'
La respuesta HTTP de un JSON-RPC válido es 200, también cuando la herramienta falla. El cuerpo trae result.structuredContent. Si el header Accept pide solo text/event-stream, la misma carga sale como evento SSE. Con application/json en el Accept, vuelve JSON.
Si a la conexión le falta el permiso, el texto de la herramienta es: Esta conexión no tiene el permiso contacts:read. Volvé a conectar Waspy y aceptá ese permiso. No es un 403 de la API REST.
Mover a ganado
curl -sS -X POST https://api.waspytech.com/mcp \
-H "Authorization: Bearer $WASPY_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "move_contact_stage",
"arguments": {
"contactId": "UUID-DEL-CONTACTO",
"stage": "ganado"
}
}
}'
structuredContent.contact trae id, name, phoneNumber, email, tags, funnelStage, temperature y lastMessageAt. No trae el objeto entero de customFields.
Qué hace el servidor, en este orden:
- La etapa tiene que estar en el catálogo. Si no, el texto es
Etapa desconocida. Usá una de: nuevo, en_conversacion, esperando, ganado, perdido(o las que tenga la cuenta). No se escribe nada. - De
tagsse sacan todas las que empiezan conetapa:. El resto (vip,mayorista) queda. - Se agrega
etapa:ganado. funnelStagese fusiona en loscustomFieldsque ya existían. Una clavelocalno se borra.
Si el UUID no es de esta cuenta, el texto es No encuentro ese contacto en esta cuenta.
Un usuario con rol de solo lectura no puede mover la etapa aunque la API key no tenga scopes. Una key sin scopes, en un usuario que no es de solo lectura, tiene acceso completo. Si la key tiene scopes, hace falta contacts:write. En el plan Pro de ChatGPT el conector no escribe: no mueve etapas ni manda notas. En Business, Enterprise y Edu, mover la etapa es una acción de bajo riesgo: no le escribe a un cliente.
El PATCH, si no usás el conector
PATCH https://api.waspytech.com/api/v2/contacts/{id} con contacts:write acepta name, email, phoneNumber, tags y customFields. tags reemplaza la lista. customFields reemplaza el objeto. La referencia de contactos dice que customFields hace merge: el handler del servidor pisa la columna. El detalle de ese cruce está en actualizar tags y customFields.
Para dejar el mismo resultado que move_contact_stage tenés que leer antes (GET /api/v2/contacts/{id}) y reenviar:
- todas las etiquetas que no empiezan con
etapa:, másetapa:ganado; - todos los
customFieldsanteriores, másfunnelStage: "ganado".
Si el body trae solo { "tags": ["etapa:ganado"] }, vip desaparece. Si además mandás customFields con una sola clave, el resto de la ficha se pierde. El alta del contacto está en contactos por API.
La nota interna, al lado
add_note pide conversationId y body (máximo 5.000 caracteres) y el scope conversations:write. La nota la ve el equipo en el panel. No se envía al cliente y no es un mensaje de Meta. El autor queda como el nombre de quien autorizó el conector, o Conector si no hay nombre. La respuesta trae note.id, note.body y note.createdAt.
No hay POST /api/v2/conversations/:id/notes. Si el asistente tiene que dejar “pasó a ganado, espera la seña”, es esta herramienta, no un WhatsApp.
Métricas, sin inventar el cupo de Meta
get_metrics pide conversations:read y un days opcional. El default es 7. El tope es 31: un 40 vuelve como 31. Devuelve messagesIn, messagesOut, openConversations, contactsByTemperature y contactsByStage.
Esos conteos son de la bandeja de Waspy. No son los 1.000 mensajes de servicio del mes ni la factura de Meta. El cupo se mira en WhatsApp Manager. En Argentina, desde el 1 de octubre de 2026, cada número tiene 1.000 mensajes de servicio por mes y, desde el 1.001, alrededor de ARS 37,68 (~US$0,026). Mover una etapa no gasta ese cupo. La rate card es la fuente. El desglose está en cuánto cuesta la API.
get_inbox_summary, con el mismo scope, devuelve openConversations, unreadConversations y hasta 10 waitingReply: chats abiertos cuyo último mensaje es del cliente.
Si la cuenta está bloqueada por pago, /mcp responde 402 y no corre la herramienta. Un lote JSON-RPC no puede pasar de 10 llamadas.
Para una campaña, la etapa es un corte de la base, no un permiso de envío. El opt-in sigue siendo aparte: cómo pedirlo y segmentar sin quemar el número.
La clave se crea en Configuración → Claves de API. Diez días de prueba, sin tarjeta, en waspytech.com.
