Skip to main content

Arquitectura Positus - WhatsApp Business API

Puede integrarse directamente con la Positus API (arriba) o usar una plataforma de atención como Invenio de Robbu, sin desarrollar la integración.
Token de Producción: Tu token será generado y proporcionado por Positus, este dará acceso a todos tus números de WhatsApp Business API. La clave será proporcionada tras la activación de cada número de WhatsApp Business API.Sandbox - Token de desarrollo: Podrás generar tu token directamente a través de http://studio.posit.us/.

Postman file

El Postman es una herramienta que tiene como objetivo probar servicios RESTful (Web APIs) mediante el envío de solicitudes HTTP y el análisis de su respuesta. Download Postman App

API de producción

Positus API (2026).postman_collection.json

API de desarrollo (Sandbox)

Positus API Sandbox (2026).postman_collection.json

messages

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Utiliza esta ruta para enviar mensajes de texto vía WhatsApp

Path Parameters

Headers

Request Body

Response

Destinatario: teléfono (to) o BSUID (recipient)

Todas las rutas de envío de mensajes aceptan dos formas de identificar al destinatario. Usa una U otra:
El BSUID es un identificador de usuario acotado al portafolio de negocios, entregado en el campo user_id de los webhooks. Es útil cuando el usuario adoptó un username y el teléfono (wa_id) puede no venir en el payload. Entiende el concepto en BSUID e identificadores de usuario.
Precedencia cuando to y recipient coexisten: si envías ambos campos en la misma solicitud, el teléfono (to) prevalece — el mensaje se entrega al teléfono. Por eso, envía solo uno de los dos: solo to (teléfono) o solo recipient (BSUID/parent BSUID).
Los números on-premises aceptan solo to (teléfono). El envío por recipient (BSUID) está disponible únicamente para números en la Cloud API (Meta).

Request Body (envío a un BSUID)

Response (envío a un BSUID)

La respuesta es la misma que en los demás envíos, pero el bloque contacts — reenviado de Meta — trae el identificador que usaste en input, además del teléfono (wa_id, cuando esté disponible) y del BSUID (user_id).
Casos especiales que exigen teléfono (no aceptan BSUID): plantillas de autenticación de los tipos one-tap, zero-tap y copy-code. En esos casos, informa siempre to (teléfono). Si envías un BSUID donde no es compatible, Meta responde con el error 131062.

Indicador de escritura

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages/typing-indicator Muestra el indicador “escribiendo…” para el cliente y marca como leído el mensaje recibido. Informa el message_id del mensaje enviado por el cliente. El indicador se descarta automáticamente después de aproximadamente 25 segundos o en cuanto respondes.

Path Parameters

Headers

Request Body

Response

HSM

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Utiliza esta ruta para enviar mensajes de notificación vía WhatsApp HSM - Son plantillas de mensajes preaprobadas por Facebook, pueden ser mensajes de texto, medios o archivos.
El destinatario puede informarse por teléfono (to) o por BSUID (recipient), como se describe en Destinatario: teléfono (to) o BSUID (recipient). Excepción: las plantillas de autenticación one-tap, zero-tap y copy-code exigen el teléfono (to) y no aceptan BSUID.

Path Parameters

Headers

Request Body

Response

Contact

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Comparte contactos

Path Parameters

Headers

Request Body

Response

Location

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Comparte ubicaciones

Path Parameters

Headers

Request Body

Response

Image

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Comparte imágenes

Path Parameters

Headers

Request Body

Response

Document

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Comparte documentos

Path Parameters

Headers

Request Body

Response

Video

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Comparte videos

Path Parameters

Headers

Request Body

Response

Audio

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Comparte audios

Path Parameters

Headers

Request Body

Response

Sticker

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Comparte stickers. El formato del sticker tiene que ser exactamente 512x512

Path Parameters

Headers

Request Body

Response

Upload de Medios

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/send-media Envía un archivo a Meta y devuelve el ID del medio. Usa ese ID en el campo id de los mensajes de medios (image, document, video, audio, sticker) cuando no quieras exponer una URL pública en el campo link.

Path Parameters

Headers

Request Body

La solicitud es multipart/form-data, con el archivo en el campo media.
Positus valida solamente el tamaño del archivo. Los tipos aceptados los define Meta según el tipo de mensaje que pretendes enviar (por ejemplo, image/jpeg, image/png, application/pdf, video/mp4, audio/ogg). Un archivo de tipo no soportado es rechazado por Meta y devuelve 422.

Response

El campo id es el ID del medio en Meta, listo para usarse en el envío de mensajes.
Ejemplo de envío de mensaje usando el id devuelto:
El ID del medio es temporal en Meta. Haz el envío del archivo y manda el mensaje a continuación, sin almacenar el ID por largos periodos.

Consultar Medio por ID

GET https://api.positus.global/v2/whatsapp/numbers/{{chave}}/media-by-id/{{messages.type.id}} Devuelve los metadatos del medio en JSON, incluyendo una URL de Positus para descargar el archivo.
Diferencia con Download Medios:
  • GET /media/{{id}} devuelve el contenido binario del archivo, con el Content-Type correspondiente.
  • GET /media-by-id/{{id}} devuelve un JSON con id, url, mime_type, sha256, size y messaging_product. Usa esta ruta cuando prefieras recibir un enlace para descargar el archivo después, en lugar de recibir los bytes en la propia respuesta.

Path Parameters

Headers

Response

Si el medio ya fue descargado antes, Positus responde directamente desde su propio almacenamiento, sin consultar a Meta. En ese caso el campo sha256 viene null. De lo contrario, Positus busca el medio en Meta, almacena el archivo y devuelve los metadatos completos.
El ID del medio en Meta es efímero y cada consulta consume la cuota de solicitudes de la aplicación. Descarga y guarda el archivo en tu aplicación en lugar de consultar el mismo ID repetidamente. Cuando Meta responde 429, respeta el encabezado Retry-After antes de volver a intentarlo.

Download Medios

GET https://api.positus.global/v2/whatsapp/numbers/{{chave}}/media/{{messages.type.id}} Descarga los medios. Usa el id del medio recibido en la notificación de webhook.

Path Parameters

Headers

Response

Devuelve el contenido binario del medio, con el encabezado Content-Type correspondiente al tipo del archivo (ej.: image/jpeg, audio/ogg, application/pdf).

Mensajes Interactivos - Lista

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Listar Mensajes: Mensajes que incluyen un menú de hasta 10 opciones. Este tipo de mensaje ofrece una manera más simple y consistente para que los usuarios hagan una selección al interactuar con una empresa. Los mensajes de botón de lista o de respuesta no pueden usarse como notificaciones. Actualmente, solo pueden enviarse dentro de las 24 horas del último mensaje enviado por el usuario. Si intentas enviar un mensaje fuera de la ventana de 24 horas, recibirás un mensaje de error.

Path Parameters

Headers

Request Body

Response

Mensajes Interactivos - Botones

POST https://api.positus.global/v2/whatsapp/numbers/{{chave}}/messages Botones de respuesta: Mensajes que incluyen hasta 3 opciones — cada opción es un botón. Este tipo de mensaje ofrece una manera más rápida para que los usuarios hagan una selección a partir de un menú al interactuar con una empresa. Los botones de respuesta tienen la misma experiencia de usuario que las plantillas interactivas con botones. Los mensajes de botón de lista o de respuesta no pueden usarse como notificaciones. Actualmente, solo pueden enviarse dentro de las 24 horas del último mensaje enviado por el usuario. Si intentas enviar un mensaje fuera de la ventana de 24 horas, recibirás un mensaje de error.

Path Parameters

Headers

Request Body

Response