Fuente: https://crm.begraffic.com/docs/api Índice para agentes: [llms.txt](https://crm.begraffic.com/llms.txt) # POST /api/v1/messaging/messages URL base: https://crm.begraffic.com. Autenticación: Authorization: Bearer . Definición OpenAPI de la operación (los bloques schema son esquemas, no cuerpos de ejemplo): ```json { "operationId": "messaging.send", "summary": "Iniciar o continuar una conversación WhatsApp/SMS.", "description": "Idempotency-Key obligatoria para evitar duplicados. Sin integración disponible: 403 feature_disabled. WhatsApp requiere plantilla fuera de la ventana. El destino debe ser E.164. SMS admite hasta 1600 caracteres y consume saldo.", "tags": [ "Conversaciones" ], "x-scope": "conversations:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "201": { "description": "Correcto.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "conversationId": { "type": "string" }, "channel": { "type": "string", "enum": [ "whatsapp", "telegram", "sms", "email" ] }, "messageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "sent", "queued" ] } }, "required": [ "conversationId", "channel", "messageId", "status" ] } } } } } }, "400": { "description": "`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized`: Falta la clave, no existe, está revocada o caducó.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`quota_exceeded`: Cuota mensual del plan agotada: reintentar no lo arregla. `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`invalid_state`: Operación no válida en el estado actual. `conflict`: Conflicto con el estado actual (p. ej. ya existe). `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal`: Error interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`unavailable`: Servicio no disponible temporalmente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "channel": { "type": "string", "const": "whatsapp" }, "to": { "type": "string", "pattern": "^\\+[1-9]\\d{9,14}$" }, "phoneNumberId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/]+$" }, "leadId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/]+$" }, "message": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string", "minLength": 1, "maxLength": 4096 }, "previewUrl": { "type": "boolean" } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "template" }, "template": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "description": "Código exacto de Meta (`es`, `es_MX`…).", "type": "string", "minLength": 2, "maxLength": 15 }, "components": { "maxItems": 20, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "template" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "interactive" }, "interactive": { "oneOf": [ { "type": "object", "properties": { "body": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "required": [ "text" ], "additionalProperties": false }, "footer": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "text" ], "additionalProperties": false }, "type": { "type": "string", "const": "button" }, "action": { "type": "object", "properties": { "buttons": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "reply" }, "reply": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "title": { "type": "string", "minLength": 1, "maxLength": 20 } }, "required": [ "id", "title" ], "additionalProperties": false } }, "required": [ "type", "reply" ], "additionalProperties": false } } }, "required": [ "buttons" ], "additionalProperties": false } }, "required": [ "body", "type", "action" ], "additionalProperties": false }, { "type": "object", "properties": { "body": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "required": [ "text" ], "additionalProperties": false }, "footer": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "text" ], "additionalProperties": false }, "type": { "type": "string", "const": "list" }, "action": { "type": "object", "properties": { "button": { "type": "string", "minLength": 1, "maxLength": 20 }, "sections": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 24 }, "rows": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "title": { "type": "string", "minLength": 1, "maxLength": 24 }, "description": { "type": "string", "minLength": 1, "maxLength": 72 } }, "required": [ "id", "title" ], "additionalProperties": false } } }, "required": [ "rows" ], "additionalProperties": false } } }, "required": [ "button", "sections" ], "additionalProperties": false } }, "required": [ "body", "type", "action" ], "additionalProperties": false }, { "type": "object", "properties": { "body": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "required": [ "text" ], "additionalProperties": false }, "footer": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "text" ], "additionalProperties": false }, "type": { "type": "string", "const": "cta_url" }, "action": { "type": "object", "properties": { "name": { "type": "string", "const": "cta_url" }, "parameters": { "type": "object", "properties": { "display_text": { "type": "string", "minLength": 1, "maxLength": 20 }, "url": { "type": "string", "maxLength": 2000, "format": "uri" } }, "required": [ "display_text", "url" ], "additionalProperties": false } }, "required": [ "name", "parameters" ], "additionalProperties": false } }, "required": [ "body", "type", "action" ], "additionalProperties": false } ] } }, "required": [ "type", "interactive" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "image": { "type": "object", "properties": { "link": { "type": "string", "maxLength": 2000, "format": "uri" }, "caption": { "type": "string", "maxLength": 1024 } }, "required": [ "link" ], "additionalProperties": false } }, "required": [ "type", "image" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "audio" }, "audio": { "type": "object", "properties": { "link": { "type": "string", "maxLength": 2000, "format": "uri" } }, "required": [ "link" ], "additionalProperties": false } }, "required": [ "type", "audio" ], "additionalProperties": false } ] } }, "required": [ "channel", "to", "message" ], "additionalProperties": false }, { "type": "object", "properties": { "channel": { "type": "string", "const": "sms" }, "to": { "type": "string", "pattern": "^\\+[1-9]\\d{9,14}$" }, "phoneNumberId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/]+$" }, "leadId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/]+$" }, "text": { "type": "string", "minLength": 1, "maxLength": 1600 }, "messageType": { "type": "string", "enum": [ "TRANSACTIONAL", "PROMOTIONAL" ] } }, "required": [ "channel", "to", "text" ], "additionalProperties": false } ] } } } } } ```