API de WhatsApp en Postman: colección lista

Actualizado el 29/10/2026

Para probar la API de WhatsApp en Postman necesitas tres datos (el Phone Number ID, un token de acceso y el número de destino), un environment con esas variables y solicitudes POST a https://graph.facebook.com/v26.0/{{phone_number_id}}/messages. Meta mantiene un workspace público en Postman con colecciones de la WhatsApp Business Platform, pero una colección mínima propia, con 5 o 6 solicitudes, suele ser más fácil de entender y de versionar. Esta guía muestra los dos caminos e incluye el JSON listo para importar.

¿Colección oficial de Meta o colección propia?

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

Un cuidado: la antigua página «Postman Collection for WhatsApp Business APIs» de la documentación era de la API On-Premises, que fue descontinuada (su última versión expiró el 23/10/2025). Los tutoriales que piden importar archivos de GitHub con un environment «WABiz» son de esa API antigua.

La recomendación práctica: usa la colección 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ónde está, revisa dónde encontrar el Phone Number ID, el WABA ID y el App ID.

Qué necesitas antes de abrir Postman

Una app de Meta con el caso de uso de WhatsApp y un número de prueba o tu número de producción. La guía de primeros pasos de Meta explica cómo obtener acceso.
El Phone Number ID del número que va a enviar. Aparece en el panel API Setup de la app, según la guía de primeros pasos de Meta.
Un token de acceso. El botón Generate access token de API Setup genera un token temporal, útil 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.
Un número de destino que controles, en formato internacional sin + (ej.: 5215512345678 para un celular de México o 5491112345678 para uno de Argentina). Con el número de prueba de Meta, el destinatario debe registrarse en el propio API Setup.

Para el contexto general, consulta la guía completa de la API oficial de WhatsApp.

¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →

Paso 1: crea el environment

En Postman, un environment es un conjunto de variables que eliges en el selector de la esquina superior derecha; solo uno está activo a la vez. Haces referencia a una variable escribiendo su nombre entre llaves dobles, como {{phone_number_id}}, y si el mismo nombre existe en más de un ámbito, gana el más específico (variables en Postman).

Guarda el JSON de abajo como whatsapp-prueba.postman_environment.json e impórtalo con el botón Import. Es el formato que Postman usa al exportar un environment:

{
  "name": "WhatsApp - prueba",
  "values": [
    { "key": "graph_url", "value": "https://graph.facebook.com", "type": "default", "enabled": true },
    { "key": "version", "value": "v26.0", "type": "default", "enabled": true },
    { "key": "phone_number_id", "value": "", "type": "default", "enabled": true },
    { "key": "meta_token", "value": "", "type": "secret", "enabled": true },
    { "key": "vectalk_url", "value": "https://apis.vectalk.com.br/api", "type": "default", "enabled": true },
    { "key": "vectalk_token", "value": "", "type": "secret", "enabled": true },
    { "key": "to", "value": "5511999999999", "type": "default", "enabled": true }
  ],
  "_postman_variable_scope": "environment"
}

Después de importar, completa phone_number_id, meta_token y to dentro de Postman, no en el archivo. Según la documentación de environments, 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ón Secure) para que no se vean en pantalla.

Paso 2: importa la colección mínima

La colección de abajo sigue el formato Postman Collection v2.1 (el campo info.schema apunta al schema oficial). Tiene dos carpetas: una para la Cloud API de Meta y otra para la API de Vectalk, cada una con su propia autenticación Bearer. Un script de prueba en la raíz verifica el estado 200 y guarda el wamid del último mensaje enviado en la variable last_wamid.

{
  "info": {
    "name": "WhatsApp API - pruebas",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "event": [{
    "listen": "test",
    "script": {
      "type": "text/javascript",
      "exec": [
        "pm.test('HTTP 200', () => pm.response.to.have.status(200));",
        "const body = pm.response.json();",
        "if (body.messages && body.messages[0]) {",
        "  pm.environment.set('last_wamid', body.messages[0].id);",
        "}"
      ]
    }
  }],
  "item": [
    {
      "name": "Meta (Cloud API)",
      "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{meta_token}}", "type": "string" }] },
      "item": [
        {
          "name": "Enviar texto",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": "{{graph_url}}/{{version}}/{{phone_number_id}}/messages",
            "body": { "mode": "raw", "raw": "{\"messaging_product\": \"whatsapp\", \"to\": \"{{to}}\", \"type\": \"text\", \"text\": {\"body\": \"Prueba desde Postman\"}}" }
          }
        },
        {
          "name": "Enviar plantilla hello_world",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": "{{graph_url}}/{{version}}/{{phone_number_id}}/messages",
            "body": { "mode": "raw", "raw": "{\"messaging_product\": \"whatsapp\", \"to\": \"{{to}}\", \"type\": \"template\", \"template\": {\"name\": \"hello_world\", \"language\": {\"code\": \"en_US\"}}}" }
          }
        },
        {
          "name": "Enviar imagen por enlace",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": "{{graph_url}}/{{version}}/{{phone_number_id}}/messages",
            "body": { "mode": "raw", "raw": "{\"messaging_product\": \"whatsapp\", \"to\": \"{{to}}\", \"type\": \"image\", \"image\": {\"link\": \"https://ejemplo.com/prueba.jpg\", \"caption\": \"Imagen de prueba\"}}" }
          }
        }
      ]
    },
    {
      "name": "Vectalk",
      "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{vectalk_token}}", "type": "string" }] },
      "item": [
        {
          "name": "Enviar texto",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": "{{vectalk_url}}/messages",
            "body": { "mode": "raw", "raw": "{\"messaging_product\": \"whatsapp\", \"to\": \"{{to}}\", \"type\": \"text\", \"text\": {\"body\": \"Prueba desde Postman\"}}" }
          }
        },
        { "name": "Listar plantillas", "request": { "method": "GET", "url": "{{vectalk_url}}/templates" } },
        { "name": "Datos del número", "request": { "method": "GET", "url": "{{vectalk_url}}/phone-numbers" } }
      ]
    }
  ]
}

Guárdala como whatsapp-api.postman_collection.json, impórtala, selecciona el environment «WhatsApp – prueba» y ejecuta las solicitudes en el orden siguiente.

Paso 3: envía el primer mensaje (plantilla)

Empieza por la plantilla hello_world. Es la plantilla que usa la guía de primeros pasos de Meta para el envío de prueba y, por ser plantilla, puede enviarse a alguien que nunca escribió a tu número: fuera de la ventana de atención de 24 horas, solo pasan plantillas. El cuerpo enviado es este:

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": { "code": "en_US" }
  }
}

Si el envío es aceptado, la respuesta tiene el formato descrito en la referencia de envío de mensajes:

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "5511999999999", "wa_id": "5511999999999" }],
  "messages": [{ "id": "wamid.HBgLNTUxMTk5OTk5OTk5...", "message_status": "accepted" }]
}

El campo message_status solo aparece cuando la plantilla enviada está bajo pacing (valores accepted o held_for_quality_assessment). Ojo: el 200 significa que la API aceptó la solicitud, no que el mensaje se entregó. La entrega se informa después por el webhook de estado (sent, delivered, read o failed); consulta estado de mensajes por webhook. Para plantillas con variables, multimedia en el encabezado y botones, el siguiente paso es la guía de cómo enviar una plantilla por la API de WhatsApp.

Paso 4: texto y multimedia

Cuando respondas el mensaje de prueba desde el celular, se abre la ventana de atención y las solicitudes Enviar texto y Enviar imagen por enlace empiezan a funcionar. El cuerpo de texto es el más simple de la API: type: "text" y el contenido en text.body.

En la imagen, cambia https://ejemplo.com/prueba.jpg por una URL pública HTTPS. Meta indica que la Cloud API guarda en caché durante 10 minutos el archivo enviado por enlace; si cambias la imagen en tu servidor y reenvías la misma URL dentro de ese plazo, puedes recibir la versión anterior. Para forzar la descarga, agrega un parámetro aleatorio a la URL (ej.: ?v=2). Formatos, límites de tamaño y envío por id de carga están en la guía de cómo enviar imagen, PDF, audio y video.

Paso 5: lee los errores

Cuando algo falla, la Cloud API devuelve un objeto error. Según la página de códigos de error de Meta, el formato es este:

{
  "error": {
    "message": "(#130429) Rate limit hit",
    "type": "OAuthException",
    "code": 130429,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Cloud API message throughput has been reached."
    },
    "fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
  }
}

Los errores que más aparecen al probar en Postman:

Código	Qué significa	Qué hacer
`190`	Token vencido	Genera un token nuevo o usa un token de usuario del sistema
`10`	Permiso no otorgado o revocado	Revisa los permisos del token
`100`	Parámetro no admitido o mal escrito	Revisa el JSON y el Phone Number ID en la URL
`131047`	Pasaron más de 24 horas desde la última respuesta del cliente	Envía una plantilla
`132000`	La cantidad de variables no coincide con la plantilla	Ajusta los `parameters`
`132001`	La plantilla no existe en ese idioma o no está aprobada	Revisa `name` y `language.code`
`133010`	Número no registrado en la plataforma	Registra el número primero

Guarda siempre el fbtrace_id: es lo que pide el soporte de Meta para investigar un caso. La lista completa, con causas y soluciones, está en errores de la API de WhatsApp, y los errores de parámetros de plantilla tienen su propio artículo, errores 132000 y 132012.

Consejos para que la colección no se desordene

Un environment por número o etapa. «WhatsApp – prueba» y «WhatsApp – producción» con las mismas claves evitan disparar una prueba desde el número real.
Nunca exportes el environment con el token completo. Si lo versionas en Git, deja meta_token y vectalk_token vacíos en el archivo.
Prueba el webhook en paralelo. Postman muestra la respuesta síncrona; lo demás (estados y respuestas del cliente) llega al webhook. Para recibir los eventos en tu máquina, revisa cómo probar el webhook localmente con ngrok.

Cómo probar la API de Vectalk en Postman

Vectalk es un proxy de la WhatsApp Cloud API: el cuerpo de los mensajes es el mismo de Meta, solo cambian la URL base y el token. La carpeta Vectalk de la colección ya usa las rutas de la documentación de Vectalk:

POST {{vectalk_url}}/messages envía cualquier tipo de mensaje, con el mismo JSON de la Cloud API.
GET {{vectalk_url}}/templates lista las plantillas de la cuenta (acepta ?name= para filtrar).
GET {{vectalk_url}}/phone-numbers devuelve los datos del número, como el nombre verificado y quality_rating.

El token se crea en el panel, en Configuraciones → API Tokens, y se muestra una sola vez. Usa un token de instancia: con él, el phone_number_id se resuelve automáticamente, y las plantillas y la multimedia exigen este tipo de token. Con un token de organización, debes enviar phone_number_id en el cuerpo del mensaje. Según la página de autenticación, 401 Unauthorized indica un token ausente o inválido y 403 Forbidden indica un token válido sin permiso para el recurso, como un token de organización que llama a /templates.

En Vectalk, cada mensaje entregado se descuenta del saldo prepago de la plataforma, así que las pruebas con el número real también consumen saldo. Para crear tu cuenta, entra a apps.vectalk.com.br/register.

Preguntas frecuentes

¿Meta tiene una colección oficial de WhatsApp en Postman?

Sí. Meta mantiene el workspace público «WhatsApp Business Platform» en Postman, enlazado desde el blog de desarrolladores de Meta y desde la documentación de la Flows API. Haz un fork a tu cuenta y completa el environment con tus IDs y tu token.

¿Por qué recibo el error 190 en Postman?

Tu token venció. El token generado en API Setup es temporal; para pruebas frecuentes, crea un token de usuario del sistema y actualiza la variable meta_token.

¿Un 200 en Postman garantiza que el mensaje se entregó?

No. El 200 indica que la API aceptó la solicitud. La entrega y la lectura se informan después por el webhook de estado.

Fuentes oficiales consultadas el 29/10/2026: Get started (Meta), Send messages (Meta), Error codes (Meta), Flows API (Meta), On-Premises API sunset (Meta), Blog de desarrolladores de Meta sobre Postman, Workspace WhatsApp Business Platform en Postman, Variables (Postman), Environment variables (Postman), Schema Collection v2.1 (Postman), Guía rápida (Vectalk), Autenticación (Vectalk).

Pon a funcionar el WhatsApp oficial de tu empresa

Crea tu cuenta, conecta tu número a la API oficial (puedes mantener la app con coexistencia) y empieza a atender y enviar mensajes.

Crear cuenta gratis

Leer la documentación

Cómo probar la API de WhatsApp en Postman (con colección lista)