Mensageria — API Zyron Connect Suite

Módulo

Mensajería

API WhatsApp unificada: envía, sigue y consulta texto, plantillas, multimedia, ubicación, contactos, interactividad y reacciones.

POST/messages/messages POST/messages/messages POST/messages/messages POST/messages/messages POST/messages/messages GET/messages/messages GET/messages/:id/messages/:id POST/messages/:id/read/messages/:id/read

POST/messagesAlcance: writeOficial + Básico

Envía un mensaje WhatsApp tipado.

Para responder usa conversation_id; para iniciar usa connection_id + recipient. Recipient acepta teléfono, contacto, BSUID, parent BSUID o username. type predeterminado es text — el único tipo de la conexión del plan Básico; los demás exigen conexión Oficial y plan Oficial/Agency. Authorization con la API key es la única credencial obligatoria. Idempotency-Key es opcional y recomendada para reintentos.

Parámetros de ruta

Sin parámetros adicionales.

Parámetros de query

Sin parámetros adicionales.

Campos del cuerpo

Campo	Tipo	Descripción
`Idempotency-Key`opcional	header	Opcional y recomendada para reintentos idempotentes (8–128 caracteres).
`text`opcional	string	Texto; obligatorio cuando type=text.
`type`opcional	text \| template \| image \| video \| audio \| document \| sticker \| location \| contacts \| interactive \| reaction	Tipo de mensaje. Predeterminado text.
`template`opcional	object	Para template: name, language y components.
`media`opcional	object	Para multimedia: link o id.
`interactive`opcional	object	Objeto interactivo nativo de Meta.
`reply_to_message_id`opcional	string	WAMID del mensaje a responder.
`biz_opaque_callback_data`opcional	string	Correlación devuelta por Meta en estados (máximo 512).
`conversation_id`opcional	uuid	Úsalo para responder una conversación existente.
`connection_id`opcional	uuid	Conexión usada para iniciar una conversación nueva.
`recipient`opcional	object	Para iniciar: phone, contact_id, BSUID, parent BSUID o username.
`to`opcional	string	Legado: equivale a recipient.phone.

Ejemplos listos

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "conversation_id": "<CONVERSATION_ID>",
  "type": "text",
  "text": "Ola, Maria. Posso te ajudar?"
}'

Respuestas

202	Meta aceptó el envío; consulta el estado en historial o webhook.
404	Conversación o conexión no encontrada.
422	text ausente o destino incompleto.

Ejemplo de respuesta

{
  "data": {
    "conversation_id": "<CONVERSATION_ID>",
    "provider_message_id": "wamid.HBgM...",
    "type": "text",
    "recipient": { "phone": "5511999998888", "business_scoped_user_id": "BR.4389531741319467" },
    "accepted": true,
    "delivery_status": "pending"
  }
}

POST/messagesAlcance: writeOficial (Meta)Requiere plan Oficial o Agency

Envía imagen, video, documento o sticker.

Usa media.id de POST /media o media.link público.

Parámetros de ruta

Sin parámetros adicionales.

Parámetros de query

Sin parámetros adicionales.

Campos del cuerpo

Campo	Tipo	Descripción
`connection_id`obligatorio	uuid	Número Oficial que envía.
`recipient.phone`obligatorio	string	Teléfono con DDI.
`type`obligatorio	image \| video \| document \| sticker	Tipo del archivo.
`media.id`opcional	string	ID de POST /media.
`media.link`opcional	URL	Alternativa pública.

Ejemplos listos

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "connection_id": "<CONNECTION_ID>",
  "recipient": { "phone": "<TELEFONE_COM_DDI>" },
  "type": "image",
  "media": { "id": "<MEDIA_ID>", "caption": "Proposta em anexo" }
}'

Respuestas

202	Archivo aceptado; sigue el wamid.

POST/messagesAlcance: writeOficial (Meta)Requiere plan Oficial o Agency

Envía audio o nota de voz.

Sube primero y usa media.id.

Parámetros de ruta

Sin parámetros adicionales.

Parámetros de query

Sin parámetros adicionales.

Campos del cuerpo

Campo	Tipo	Descripción
`media.id`obligatorio	string	ID de upload.

Ejemplos listos

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "connection_id": "<CONNECTION_ID>",
  "recipient": { "phone": "<TELEFONE_COM_DDI>" },
  "type": "audio",
  "media": { "id": "<MEDIA_ID>" }
}'

Respuestas

202	Audio aceptado.

POST/messagesAlcance: writeOficial (Meta)Requiere plan Oficial o Agency

Envía plantilla aprobada.

Úsalo fuera de la ventana de 24 h.

Parámetros de ruta

Sin parámetros adicionales.

Parámetros de query

Sin parámetros adicionales.

Campos del cuerpo

Campo	Tipo	Descripción
`template.name`obligatorio	string	Nombre aprobado exacto.
`template.components`opcional	array	Parámetros.

Ejemplos listos

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "connection_id": "<CONNECTION_ID>",
  "recipient": { "phone": "<TELEFONE_COM_DDI>" },
  "type": "template",
  "template": { "name": "NOME_DO_TEMPLATE", "language": "pt_BR", "components": [] }
}'

Respuestas

202	Template aceptado.

POST/messagesAlcance: writeOficial (Meta)Requiere plan Oficial o Agency

Envía botones, lista, ubicación, contactos o reacción.

Cambia type y su objeto.

Parámetros de ruta

Sin parámetros adicionales.

Parámetros de query

Sin parámetros adicionales.

Campos del cuerpo

Campo	Tipo	Descripción
`interactive \| location \| contacts \| reaction`opcional	object	Contenido del tipo elegido.

Ejemplos listos

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "conversation_id": "<CONVERSATION_ID>",
  "type": "location",
  "location": { "latitude": -22.879, "longitude": -43.104, "name": "Local do atendimento" }
}'

Respuestas

202	Mensaje especial aceptado.

GET/messagesAlcance: readOficial + Básico

Lista mensajes y estados.

Filtra por conexión, conversación, contacto, dirección, estado o WAMID.

Parámetros de ruta

Sin parámetros adicionales.

Parámetros de query

Campo	Tipo	Descripción
`connection_id`opcional	uuid	Conexión WhatsApp.
`conversation_id`opcional	uuid	Conversación interna.
`provider_message_id`opcional	string	WAMID/ID del provider.
`limit`opcional	number	Cantidad de registros por página. Predeterminado 50; máximo 200 en la mayoría de listas.
`offset`opcional	number	Índice inicial de la página. Usa pagination.next_offset para la siguiente página.

Campos del cuerpo

Este endpoint no recibe cuerpo JSON.

Ejemplos listos

curl -X GET "https://connect.zyronstack.com/api/v1/messages?connection_id=<CONNECTION_ID>&provider_message_id=wamid.HBgM..." \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respuestas

200	Mensajes paginados.

GET/messages/:idAlcance: readOficial + Básico

Consulta un mensaje con payload.

Lee metadatos sin perder el payload original.

Parámetros de ruta

Campo	Tipo	Descripción
`id`obligatorio	integer	ID interno del log.

Parámetros de query

Sin parámetros adicionales.

Campos del cuerpo

Este endpoint no recibe cuerpo JSON.

Ejemplos listos

curl -X GET "https://connect.zyronstack.com/api/v1/messages/42" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respuestas

200	Mensaje devuelto.

POST/messages/:id/readAlcance: writeOficial (Meta)

Marca un mensaje inbound como leído.

Disponible para conexión Oficial; usa el WAMID guardado.

Parámetros de ruta

Campo	Tipo	Descripción
`id`obligatorio	integer	ID interno del log inbound.

Parámetros de query

Sin parámetros adicionales.

Campos del cuerpo

Este endpoint no recibe cuerpo JSON.

Ejemplos listos

curl -X POST "https://connect.zyronstack.com/api/v1/messages/42/read" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respuestas

200	Lectura confirmada.
422	Conexión no soporta lectura.