{"id":803,"date":"2026-10-29T13:31:23","date_gmt":"2026-10-29T13:31:23","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/probar-api-whatsapp-postman\/"},"modified":"2026-10-29T13:31:38","modified_gmt":"2026-10-29T13:31:38","slug":"probar-api-whatsapp-postman","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/es\/probar-api-whatsapp-postman\/","title":{"rendered":"C\u00f3mo probar la API de WhatsApp en Postman (con colecci\u00f3n lista)"},"content":{"rendered":"\n

Actualizado el 29\/10\/2026<\/em><\/p>\n\n\n\n

Para probar la API de WhatsApp en Postman necesitas tres datos (el Phone Number ID, un token de acceso y el n\u00famero de destino), un environment<\/em> con esas variables y solicitudes POST<\/code> a https:\/\/graph.facebook.com\/v26.0\/{{phone_number_id}}\/messages<\/code>. Meta mantiene un workspace p\u00fablico en Postman con colecciones de la WhatsApp Business Platform, pero una colecci\u00f3n m\u00ednima propia, con 5 o 6 solicitudes, suele ser m\u00e1s f\u00e1cil de entender y de versionar. Esta gu\u00eda muestra los dos caminos e incluye el JSON listo para importar.<\/p>\n\n\n\n

\u00bfColecci\u00f3n oficial de Meta o colecci\u00f3n propia?<\/h2>\n\n\n\n

Meta publica colecciones en el workspace WhatsApp Business Platform<\/strong>, dentro del perfil de Meta en Postman: postman.com\/meta\/workspace\/whatsapp-business-platform<\/a>. El enlace aparece en una publicaci\u00f3n del blog de desarrolladores de Meta<\/a>, que describe una colecci\u00f3n que precarga variables de entorno y gu\u00eda las primeras solicitudes, y la documentaci\u00f3n de la Flows API<\/a> apunta a la colecci\u00f3n de Flows en el mismo workspace.<\/p>\n\n\n\n

Un cuidado: la antigua p\u00e1gina “Postman Collection for WhatsApp Business APIs” de la documentaci\u00f3n era de la API On-Premises, que fue descontinuada (su \u00faltima versi\u00f3n expir\u00f3 el 23\/10\/2025). Los tutoriales que piden importar archivos de GitHub con un environment “WABiz” son de esa API antigua.<\/p>\n\n\n\n

La recomendaci\u00f3n pr\u00e1ctica: usa la colecci\u00f3n oficial como referencia para descubrir endpoints y arma la tuya con lo que tu equipo realmente llama. Antes de empezar, ten a mano el Phone Number ID; si no sabes d\u00f3nde est\u00e1, revisa d\u00f3nde encontrar el Phone Number ID, el WABA ID y el App ID<\/a>.<\/p>\n\n\n\n

Qu\u00e9 necesitas antes de abrir Postman<\/h2>\n\n\n\n
    \n
  1. Una app de Meta con el caso de uso de WhatsApp<\/strong> y un n\u00famero de prueba o tu n\u00famero de producci\u00f3n. La gu\u00eda de primeros pasos de Meta explica c\u00f3mo obtener acceso.<\/li>\n\n\n
  2. El Phone Number ID<\/strong> del n\u00famero que va a enviar. Aparece en el panel API Setup<\/strong> de la app, seg\u00fan la gu\u00eda de primeros pasos de Meta<\/a>.<\/li>\n\n\n
  3. Un token de acceso<\/strong>. El bot\u00f3n Generate access token<\/em> de API Setup genera un token temporal, \u00fatil para la primera prueba. Para uso continuo, crea un token de usuario del sistema, como se explica en token permanente de la API de WhatsApp<\/a>.<\/li>\n\n\n
  4. Un n\u00famero de destino<\/strong> que controles, en formato internacional sin +<\/code> (ej.: 5215512345678<\/code> para un celular de M\u00e9xico o 5491112345678<\/code> para uno de Argentina). Con el n\u00famero de prueba de Meta, el destinatario debe registrarse en el propio API Setup.<\/li>\n\n<\/ol>\n\n\n\n

    Para el contexto general, consulta la gu\u00eda completa de la API oficial de WhatsApp<\/a>.<\/p>\n\n\n\n

    Paso 1: crea el environment<\/h2>\n\n\n\n

    En Postman, un environment<\/em> es un conjunto de variables que eliges en el selector de la esquina superior derecha; solo uno est\u00e1 activo a la vez. Haces referencia a una variable escribiendo su nombre entre llaves dobles, como {{phone_number_id}}<\/code>, y si el mismo nombre existe en m\u00e1s de un \u00e1mbito, gana el m\u00e1s espec\u00edfico (variables en Postman<\/a>).<\/p>\n\n\n\n

    Guarda el JSON de abajo como whatsapp-prueba.postman_environment.json<\/code> e imp\u00f3rtalo con el bot\u00f3n Import<\/strong>. Es el formato que Postman usa al exportar un environment:<\/p>\n\n\n\n

    {\n  \"name\": \"WhatsApp - prueba\",\n  \"values\": [\n    { \"key\": \"graph_url\", \"value\": \"https:\/\/graph.facebook.com\", \"type\": \"default\", \"enabled\": true },\n    { \"key\": \"version\", \"value\": \"v26.0\", \"type\": \"default\", \"enabled\": true },\n    { \"key\": \"phone_number_id\", \"value\": \"\", \"type\": \"default\", \"enabled\": true },\n    { \"key\": \"meta_token\", \"value\": \"\", \"type\": \"secret\", \"enabled\": true },\n    { \"key\": \"vectalk_url\", \"value\": \"https:\/\/apis.vectalk.com.br\/api\", \"type\": \"default\", \"enabled\": true },\n    { \"key\": \"vectalk_token\", \"value\": \"\", \"type\": \"secret\", \"enabled\": true },\n    { \"key\": \"to\", \"value\": \"5511999999999\", \"type\": \"default\", \"enabled\": true }\n  ],\n  \"_postman_variable_scope\": \"environment\"\n}<\/code><\/pre>\n\n\n\n
    Despu\u00e9s de importar, completa phone_number_id<\/code>, meta_token<\/code> y to<\/code> dentro de Postman, no en el archivo. Seg\u00fan la documentaci\u00f3n de environments<\/a>, el valor local de una variable no se sincroniza con la nube de Postman ni se comparte con el equipo, salvo que decidas compartirlo. Marca los tokens como seguros (opci\u00f3n Secure<\/em>) para que no se vean en pantalla.<\/p>\n\n\n\n
    Paso 2: importa la colecci\u00f3n m\u00ednima<\/h2>\n\n\n\n
    La colecci\u00f3n de abajo sigue el formato Postman Collection v2.1<\/strong> (el campo info.schema<\/code> apunta al schema oficial<\/a>). Tiene dos carpetas: una para la Cloud API de Meta y otra para la API de Vectalk, cada una con su propia autenticaci\u00f3n Bearer<\/em>. Un script de prueba en la ra\u00edz verifica el estado 200 y guarda el wamid<\/code> del \u00faltimo mensaje enviado en la variable last_wamid<\/code>.<\/p>\n\n\n\n
    {\n  \"info\": {\n    \"name\": \"WhatsApp API - pruebas\",\n    \"schema\": \"https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json\"\n  },\n  \"event\": [{\n    \"listen\": \"test\",\n    \"script\": {\n      \"type\": \"text\/javascript\",\n      \"exec\": [\n        \"pm.test('HTTP 200', () => pm.response.to.have.status(200));\",\n        \"const body = pm.response.json();\",\n        \"if (body.messages && body.messages[0]) {\",\n        \"  pm.environment.set('last_wamid', body.messages[0].id);\",\n        \"}\"\n      ]\n    }\n  }],\n  \"item\": [\n    {\n      \"name\": \"Meta (Cloud API)\",\n      \"auth\": { \"type\": \"bearer\", \"bearer\": [{ \"key\": \"token\", \"value\": \"{{meta_token}}\", \"type\": \"string\" }] },\n      \"item\": [\n        {\n          \"name\": \"Enviar texto\",\n          \"request\": {\n            \"method\": \"POST\",\n            \"header\": [{ \"key\": \"Content-Type\", \"value\": \"application\/json\" }],\n            \"url\": \"{{graph_url}}\/{{version}}\/{{phone_number_id}}\/messages\",\n            \"body\": { \"mode\": \"raw\", \"raw\": \"{\\\"messaging_product\\\": \\\"whatsapp\\\", \\\"to\\\": \\\"{{to}}\\\", \\\"type\\\": \\\"text\\\", \\\"text\\\": {\\\"body\\\": \\\"Prueba desde Postman\\\"}}\" }\n          }\n        },\n        {\n          \"name\": \"Enviar plantilla hello_world\",\n          \"request\": {\n            \"method\": \"POST\",\n            \"header\": [{ \"key\": \"Content-Type\", \"value\": \"application\/json\" }],\n            \"url\": \"{{graph_url}}\/{{version}}\/{{phone_number_id}}\/messages\",\n            \"body\": { \"mode\": \"raw\", \"raw\": \"{\\\"messaging_product\\\": \\\"whatsapp\\\", \\\"to\\\": \\\"{{to}}\\\", \\\"type\\\": \\\"template\\\", \\\"template\\\": {\\\"name\\\": \\\"hello_world\\\", \\\"language\\\": {\\\"code\\\": \\\"en_US\\\"}}}\" }\n          }\n        },\n        {\n          \"name\": \"Enviar imagen por enlace\",\n          \"request\": {\n            \"method\": \"POST\",\n            \"header\": [{ \"key\": \"Content-Type\", \"value\": \"application\/json\" }],\n            \"url\": \"{{graph_url}}\/{{version}}\/{{phone_number_id}}\/messages\",\n            \"body\": { \"mode\": \"raw\", \"raw\": \"{\\\"messaging_product\\\": \\\"whatsapp\\\", \\\"to\\\": \\\"{{to}}\\\", \\\"type\\\": \\\"image\\\", \\\"image\\\": {\\\"link\\\": \\\"https:\/\/ejemplo.com\/prueba.jpg\\\", \\\"caption\\\": \\\"Imagen de prueba\\\"}}\" }\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"Vectalk\",\n      \"auth\": { \"type\": \"bearer\", \"bearer\": [{ \"key\": \"token\", \"value\": \"{{vectalk_token}}\", \"type\": \"string\" }] },\n      \"item\": [\n        {\n          \"name\": \"Enviar texto\",\n          \"request\": {\n            \"method\": \"POST\",\n            \"header\": [{ \"key\": \"Content-Type\", \"value\": \"application\/json\" }],\n            \"url\": \"{{vectalk_url}}\/messages\",\n            \"body\": { \"mode\": \"raw\", \"raw\": \"{\\\"messaging_product\\\": \\\"whatsapp\\\", \\\"to\\\": \\\"{{to}}\\\", \\\"type\\\": \\\"text\\\", \\\"text\\\": {\\\"body\\\": \\\"Prueba desde Postman\\\"}}\" }\n          }\n        },\n        { \"name\": \"Listar plantillas\", \"request\": { \"method\": \"GET\", \"url\": \"{{vectalk_url}}\/templates\" } },\n        { \"name\": \"Datos del n\u00famero\", \"request\": { \"method\": \"GET\", \"url\": \"{{vectalk_url}}\/phone-numbers\" } }\n      ]\n    }\n  ]\n}<\/code><\/pre>\n\n\n\n
    Gu\u00e1rdala como whatsapp-api.postman_collection.json<\/code>, imp\u00f3rtala, selecciona el environment “WhatsApp – prueba” y ejecuta las solicitudes en el orden siguiente.<\/p>\n\n\n\n
    Paso 3: env\u00eda el primer mensaje (plantilla)<\/h2>\n\n\n\n
    Empieza por la plantilla hello_world<\/code><\/strong>. Es la plantilla que usa la gu\u00eda de primeros pasos de Meta para el env\u00edo de prueba y, por ser plantilla, puede enviarse a alguien que nunca escribi\u00f3 a tu n\u00famero: fuera de la ventana de atenci\u00f3n de 24 horas, solo pasan plantillas. El cuerpo enviado es este:<\/p>\n\n\n\n
    {\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"5511999999999\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"hello_world\",\n    \"language\": { \"code\": \"en_US\" }\n  }\n}<\/code><\/pre>\n\n\n\n
    Si el env\u00edo es aceptado, la respuesta tiene el formato descrito en la referencia de env\u00edo de mensajes<\/a>:<\/p>\n\n\n\n
    {\n  \"messaging_product\": \"whatsapp\",\n  \"contacts\": [{ \"input\": \"5511999999999\", \"wa_id\": \"5511999999999\" }],\n  \"messages\": [{ \"id\": \"wamid.HBgLNTUxMTk5OTk5OTk5...\", \"message_status\": \"accepted\" }]\n}<\/code><\/pre>\n\n\n\n
    El campo message_status<\/code> solo aparece cuando la plantilla enviada est\u00e1 bajo pacing (valores accepted<\/code> o held_for_quality_assessment<\/code>). Ojo: el 200 significa que la API acept\u00f3<\/strong> la solicitud, no que el mensaje se entreg\u00f3. La entrega se informa despu\u00e9s por el webhook de estado (sent<\/code>, delivered<\/code>, read<\/code> o failed<\/code>); consulta estado de mensajes por webhook<\/a>. Para plantillas con variables, multimedia en el encabezado y botones, el siguiente paso es la gu\u00eda de c\u00f3mo enviar una plantilla por la API de WhatsApp<\/a>.<\/p>\n\n\n\n
    Paso 4: texto y multimedia<\/h2>\n\n\n\n
    Cuando respondas el mensaje de prueba desde el celular, se abre la ventana de atenci\u00f3n y las solicitudes Enviar texto<\/strong> y Enviar imagen por enlace<\/strong> empiezan a funcionar. El cuerpo de texto es el m\u00e1s simple de la API: type: \"text\"<\/code> y el contenido en text.body<\/code>.<\/p>\n\n\n\n
    En la imagen, cambia https:\/\/ejemplo.com\/prueba.jpg<\/code> por una URL p\u00fablica HTTPS. Meta indica que la Cloud API guarda en cach\u00e9 durante 10 minutos el archivo enviado por enlace; si cambias la imagen en tu servidor y reenv\u00edas la misma URL dentro de ese plazo, puedes recibir la versi\u00f3n anterior. Para forzar la descarga, agrega un par\u00e1metro aleatorio a la URL (ej.: ?v=2<\/code>). Formatos, l\u00edmites de tama\u00f1o y env\u00edo por id<\/code> de carga est\u00e1n en la gu\u00eda de c\u00f3mo enviar imagen, PDF, audio y video<\/a>.<\/p>\n\n\n\n
    Paso 5: lee los errores<\/h2>\n\n\n\n
    Cuando algo falla, la Cloud API devuelve un objeto error<\/code>. Seg\u00fan la p\u00e1gina de c\u00f3digos de error de Meta<\/a>, el formato es este:<\/p>\n\n\n\n
    {\n  \"error\": {\n    \"message\": \"(#130429) Rate limit hit\",\n    \"type\": \"OAuthException\",\n    \"code\": 130429,\n    \"error_data\": {\n      \"messaging_product\": \"whatsapp\",\n      \"details\": \"Cloud API message throughput has been reached.\"\n    },\n    \"fbtrace_id\": \"Az8or2yhqkZfEZ-_4Qn_Bam\"\n  }\n}<\/code><\/pre>\n\n\n\n
    Los errores que m\u00e1s aparecen al probar en Postman:<\/p>\n\n\n\n
    C\u00f3digo<\/th>Qu\u00e9 significa<\/th>Qu\u00e9 hacer<\/th><\/tr><\/thead>
    190<\/code><\/td>Token vencido<\/td>Genera un token nuevo o usa un token de usuario del sistema<\/td><\/tr>
    10<\/code><\/td>Permiso no otorgado o revocado<\/td>Revisa los permisos del token<\/td><\/tr>
    100<\/code><\/td>Par\u00e1metro no admitido o mal escrito<\/td>Revisa el JSON y el Phone Number ID en la URL<\/td><\/tr>
    131047<\/code><\/td>Pasaron m\u00e1s de 24 horas desde la \u00faltima respuesta del cliente<\/td>Env\u00eda una plantilla<\/td><\/tr>
    132000<\/code><\/td>La cantidad de variables no coincide con la plantilla<\/td>Ajusta los parameters<\/code><\/td><\/tr>
    132001<\/code><\/td>La plantilla no existe en ese idioma o no est\u00e1 aprobada<\/td>Revisa name<\/code> y language.code<\/code><\/td><\/tr>
    133010<\/code><\/td>N\u00famero no registrado en la plataforma<\/td>Registra el n\u00famero primero<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Guarda siempre el fbtrace_id<\/code>: es lo que pide el soporte de Meta para investigar un caso. La lista completa, con causas y soluciones, est\u00e1 en errores de la API de WhatsApp<\/a>, y los errores de par\u00e1metros de plantilla tienen su propio art\u00edculo, errores 132000 y 132012<\/a>.<\/p>\n\n\n\n
    Consejos para que la colecci\u00f3n no se desordene<\/h2>\n\n\n\n