Enviar mensaje de WhatsApp

POSThttps://api.bydomu.com/v1/conversations/{contactId}/messages

This reference is generated from the API’s code, so descriptions are in Spanish. Names, parameters and examples are the same in every language.

Envía un mensaje al contacto respetando la ventana de servicio de 24 h de Meta.

Ventana abierta: manda body y se entrega como texto libre (la respuesta es el mensaje guardado).
Ventana cerrada: manda templateId + variables con una plantilla APROBADA (la respuesta trae waMessageId, renderedBody y usage).
Ninguna de las dos es posible (opt-out, sin plantilla, sin ventana): 409 CONFLICT con el motivo en error.message, el modo en error.reason (FREE_FORM, TEMPLATE_ONLY, HUMAN_AGENT_ONLY, BLOCKED) y, si falta la plantilla, error.windowExpiresAt.

La API nunca envía como human_agent: esa vía es de una persona real en el buzón. Si la organización no tiene un número de WhatsApp activo, responde 404.

Permission

messages:write

Keys

Secret only (server-side)

Headers

X-API-Keystringrequired

Your secret key.

Idempotency-Keystring

Clave única de la operación (8-128 caracteres de [a-zA-Z0-9._:-]). Un reintento con la misma clave y el mismo cuerpo devuelve la respuesta original sin repetir la operación. Vive 24 horas. · 8–128 chars

Path parameters

contactIdstringrequired

ID del contacto

Body (JSON)

bodystring

Texto libre. Solo con la ventana de 24 h abierta. · 1–4096 chars

templateIdstring

Plantilla aprobada, para la ventana cerrada.

variablesobject

Valores de las variables de la plantilla. · default={}

Responses

201Mensaje enviado

400Datos inválidos: el cuerpo o la query no cumplen el esquema, o `Idempotency-Key` está mal formada.

401UNAUTHORIZED · Clave faltante, inválida, desactivada o vencida.

402PAYMENT_REQUIRED · Cuenta en modo solo lectura: se rechaza toda mutación.

403FORBIDDEN · La clave no puede usar esta operación: falta el scope, es una secreta en el navegador, el nivel de la cuenta no la permite, está suspendida o se alcanzó un tope del plan.

404NOT_FOUND · El recurso no existe en la organización.

409DUPLICATE · Choca con un dato existente o con el estado actual, o la `Idempotency-Key` ya se usó con otro cuerpo o sigue en curso.

429RATE_LIMITED · Límite de peticiones excedido: el de la clave (`RATE_LIMITED`), el de escrituras de la organización (`TENANT_RATE_LIMITED`) o bloqueo temporal de la IP por claves inválidas.

500INTERNAL_ERROR · Error interno del servidor.

502WHATSAPP_ERROR · Falló un servicio externo (Meta / WhatsApp).

curl -X POST "https://api.bydomu.com/v1/conversations/clx1con001/messages" \ -H "X-API-Key: $BYDOMU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "body": "Hola María, ¿te queda bien la visita del jueves a las 10?" }'

const res = await fetch("https://api.bydomu.com/v1/conversations/clx1con001/messages", { method: "POST", headers: { "X-API-Key": process.env.BYDOMU_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ "body": "Hola María, ¿te queda bien la visita del jueves a las 10?" }), }); const data = await res.json();

import os, requests r = requests.post( "https://api.bydomu.com/v1/conversations/clx1con001/messages", headers={"X-API-Key": os.environ["BYDOMU_API_KEY"]}, json={ "body": "Hola María, ¿te queda bien la visita del jueves a las 10?" } ) data = r.json()

{ "data": { "id": "clx1msg002", "waMessageId": "wamid.HBgMNTczMDAxMjM0NTY3FQIAERgSQzU", "channel": "WHATSAPP", "direction": "INBOUND", "type": "TEXT", "body": "Hola María, ¿te queda bien la visita del jueves a las 10?", "timestamp": "2026-09-25T10:35:00.000Z", "contactId": "clx1con001", "agentId": "clx1usr001", "agent": { "id": "clx1usr001", "firstName": "Carlos", "lastName": "Rodríguez" } } }