Volver al blog
Desarrolladores

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.

· 12 min
Cómo mover la etapa de un contacto con el conector de Waspy (sin pisar las otras etiquetas)

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 manualClasificación automática
Qué esLa etiqueta etapa:ganado y el campo funnelStagetemperature: hot, warm, silent o cold
Quién la cambiamove_contact_stage, o un PATCH armado a manoWaspy, según la actividad. Esta llamada no la toca
Cómo se leelist_funnel_stages → catalog y usagelist_funnel_stages → classification, o get_metrics → contactsByTemperature
En el panelLa etiqueta etapa:Muy activo, Activo, Silencioso, Frío
Si 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 cada funnelStage ya guardado (hasta 50 grupos).
  • classification: el conteo por temperature.

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:

  1. 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.
  2. De tags se sacan todas las que empiezan con etapa:. El resto (vip, mayorista) queda.
  3. Se agrega etapa:ganado.
  4. funnelStage se fusiona en los customFields que ya existían. Una clave local no 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ás etapa:ganado;
  • todos los customFields anteriores, más funnelStage: "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.

Tu equipo atendiendo por WhatsApp en minutos

CRM facil pero potente. En 10 minutos tenes a tu equipo trabajando — no necesitas hablar con nadie.