Fuente: https://crm.begraffic.com/docs/api Índice para agentes: [llms.txt](https://crm.begraffic.com/llms.txt) # POST /api/v1/conversations/{id}/reply 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": "conversations.reply", "summary": "Responder", "description": "Texto por el canal de la conversación (WhatsApp: dentro de la ventana de 24 h; fuera, `template`). Cuota de cada canal: WhatsApp y correo del plan, SMS del saldo (402). 201 enviado; 202 correo encolado. 409 `unknown_outcome`: el proveedor no respondió y el mensaje pudo salir; con la misma Idempotency-Key se repite esa respuesta sin reenviar. 403 `forbidden` (`sending_paused`): el envío de correo del workspace está pausado. 402 `contact_limit_exceeded`: el workspace superó su límite de contactos (contestar a mano desde el panel sigue permitido).", "tags": [ "Conversaciones" ], "x-scope": "conversations:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`{canal}__{id}` (p. ej. `whatsapp__573001234567`).", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/]+$" } }, { "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": "`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). `quota_exceeded`: Cuota mensual del plan agotada: 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. `forbidden`: Operación no permitida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: No existe (o no es de este workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`invalid_state`: Operación no válida en el estado actual. `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": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 4096 }, "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 }, "message": { "description": "Solo WhatsApp: texto, plantilla, imagen, audio, botones, lista o enlace CTA.", "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 } ] } }, "additionalProperties": false } } } } } ```