Ir al contenido

Beta privada · apertura 23 de diciembre

Envía un mensaje

POST /v1/conecta/mensajes

Envía texto, un archivo o una plantilla por la conexión indicada. Fuera de la ventana de atención solo acepta plantillas (si no, 409 ventana_cerrada con plantillas sugeridas). Si el proveedor no confirma, el mensaje queda incierto y no se reenvía solo. Los cargos de Meta por mensaje los paga tu cuenta de Meta.

Dato Valor
Permiso conecta:enviar
Cobro No cobra.
Idempotency-Key Obligatoria
Aprobación humana Según la configuración de tu clave puede responder 202 requiere_confirmacion.
Herramienta MCP mensaje_enviar (Próximamente)
Nombre En Requerido Tipo Descripción
Idempotency-Key header Sí string Identifica una operación para que repetirla no la duplique. Si repites la petición con la misma clave y el mismo cuerpo, recibes la misma respuesta; con otro cuerpo, idempotencia_en_conflicto. Se guarda 24 horas.
X-Request-Id header No string Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte.

application/json, obligatorio. Los campos anidados van con punto y los de listas con []. No se aceptan campos desconocidos.

Campo Tipo Requerido Descripción
conexion_id string Sí Identificador que empieza con con_.
conversacion_id string No Responder en una conversación existente (cualquier canal).
telefono string No Solo WhatsApp: escribir a un número.
tipo “texto” Sí
texto string No
media object No
media.tipo “imagen” | “video” | “audio” | “documento” No
media.url string (uri) No Archivo público por https; lo descargamos y lo enviamos.
media.nombre_archivo string No
media.leyenda string No
plantilla object No
plantilla.nombre string No
plantilla.idioma string No Código de idioma, por ejemplo es o es_PE.
plantilla.parametros object No
plantilla.parametros.encabezado string | object No
plantilla.parametros.cuerpo string[] No Valores de {{1}}, {{2}}… en orden.
plantilla.parametros.botones string[] No

Contra el sandbox, con una clave onx_test_…:

Ventana de terminal
curl -X POST "https://api-sandbox.opennexum.com/v1/conecta/mensajes" \
-H "Authorization: Bearer onx_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"conexion_id": "con_8f2c1a7d9e",
"tipo": "texto",
"texto": "texto"
}'

Mensaje aceptado por el proveedor.

Campo Tipo Requerido Descripción
id string Sí Identificador que empieza con msg_.
conexion_id string Sí Identificador que empieza con con_.
conversacion_id string Sí Identificador que empieza con cnv_.
canal “whatsapp” | “instagram” | “messenger” Sí
direccion “saliente” | “entrante” Sí
tipo “texto” | “media” | “plantilla” | “interactivo” | “otro” Sí
texto string | null Sí
media object | null Sí En mensajes entrantes, la URL es nuestra y vence en unas horas.
media.tipo “imagen” | “video” | “audio” | “documento” Sí
media.url string (uri) Sí
media.nombre_archivo string | null Sí
media.leyenda string | null Sí
plantilla object | null Sí
plantilla.nombre string Sí
plantilla.idioma string Sí
estado “en_cola” | “enviado” | “entregado” | “leido” | “fallido” | “incierto” | “recibido” Sí incierto: el proveedor no confirmó; revisa antes de reenviar. recibido: mensaje entrante.
error object | null Sí
error.codigo string Sí
error.mensaje string Sí
creado_en string (date-time) Sí Fecha y hora ISO 8601 con la zona de Lima (-05:00).
actualizado_en string (date-time) Sí Fecha y hora ISO 8601 con la zona de Lima (-05:00).

Espera la aprobación de una persona.

Campo Tipo Requerido Descripción
estado “requiere_confirmacion” Sí
operacion_id string Sí Úsalo en GET /v1/confirmaciones/{id} para saber si se aprobó.
confirmacion_url string (uri) Sí Enlace del panel donde una persona aprueba o rechaza. Pásaselo tal cual.
consulta_url string Sí Ruta para consultar el estado.
expira_en string (date-time) Sí Antes de esta hora hay que aprobarla Y repetir la petición; si no, vence y no se hace.
mensaje string Sí Qué falta, en palabras para una persona.

Cada código tiene su explicación en Errores.