Personalización del formulario

Personaliza el aspecto, las etiquetas y los colores de tu formulario con la Agent API.

Obtener detalles del formulario

Endpoint: GET /api/agent/form

Cabeceras:

Authorization: Bearer sr_live_your_api_key

Respuesta:

{
  "form": {
    "id": "uuid",
    "title": "Get Support",
    "description": "Fill in the following details...",
    "background_color": "f9f9fb",
    "button_color": "3f3ea2",
    "text_color": "000000",
    "logo_url": "https://...",
    "button_text": "ENVIAR",
    "field_name_label": "Nombre",
    "field_email_label": "Correo electrónico",
    "field_message_label": "Mensaje",
    "field_name_placeholder": "Túr name",
    "field_email_placeholder": "your@email.com",
    "field_message_placeholder": "Write something nice"
  },
  "embed": {
    "direct_url": "https://supportretriever.com/form/uuid",
    "iframe": "<iframe src=\"...\"></iframe>",
    "html_link": {
      "default": "<a href=\"...\">Contact Support</a>",
      "with_styles": "<a href=\"...\" style=\"...\">Contact Support</a>"
    }
  }
}

Actualizar el formulario

Endpoint: PUT /api/agent/form

Cabeceras:

Authorization: Bearer sr_live_your_api_key
Content-Type: application/json

Cuerpo de la petición (todos los campos opcionales):

{
  "title": "Contacto",
  "description": "We'd love to hear from you!",
  "background_color": "ffffff",
  "button_color": "007bff",
  "text_color": "333333",
  "logo_url": "https://example.com/logo.png",
  "button_text": "Enviar Mensaje",
  "field_name_label": "Túr Nombre",
  "field_email_label": "Túr Correo electrónico",
  "field_message_label": "Túr Mensaje",
  "field_name_placeholder": "John Doe",
  "field_email_placeholder": "john@example.com",
  "field_message_placeholder": "How can we help?"
}

Respuesta:

{
  "success": true,
  "form": {
    // Objeto del formulario actualizado
  }
}

Campos personalizables

Ajustes visuales

Campo	Tipo	Descripción	Ejemplo
`title`	string	Encabezado del formulario (máx. 100 caracteres)	"Contacto"
`description`	string	Texto de descripción	"We'd love to hear from you!"
`background_color`	string	Color hex (6 caracteres, sin #)	"ffffff"
`button_color`	string	Color del botón de envío	"007bff"
`text_color`	string	Color del texto	"333333"
`logo_url`	string	URL de la imagen del logo	"https://example.com/logo.png"
`button_text`	string	Texto del botón de envío	"Enviar Mensaje"

Etiquetas de campos

Campo	Descripción	Ejemplo
`field_name_label`	Etiqueta del campo nombre	"Túr Nombre"
`field_email_label`	Etiqueta del campo correo	"Túr Correo electrónico"
`field_message_label`	Etiqueta del campo mensaje	"Túr Mensaje"

Placeholders de campos

Campo	Descripción	Ejemplo
`field_name_placeholder`	Placeholder del nombre	"John Doe"
`field_email_placeholder`	Placeholder del correo	"john@example.com"
`field_message_placeholder`	Placeholder del mensaje	"How can we help?"

Campos protegidos

Estos campos no se pueden cambiar vía Agent API (se ignoran en silencio):

recipient_email – Correo al que se envían los envíos
custom_email_domain – Configuración de dominio de correo personalizado
custom_email_username – Usuario de correo personalizado
userID – Propietario del formulario
id – Identificador del formulario
created_at – Marca de tiempo de creación

Por qué están protegidos:

recipient_email evita el secuestro de mensajes de clientes
El resto son gestionados por el sistema

Formularioato de colores

Los colores usan formato hex sin el símbolo #:

✅ Correcto: "ffffff", "3f3ea2", "000000"
❌ Incorrecto: "#ffffff", "rgb(255,255,255)", "white"

Actualizaciones parciales

Puedes actualizar solo los campos que quieras cambiar:

{
  "title": "New Título",
  "button_color": "ff0000"
}

Solo se actualizarán title y button_color; el resto permanece igual.

Buenas prácticas

Contraste de color

Usa fondos claros (ffffff, f9f9fb) con texto oscuro (000000, 333333)
Asegura que el color del botón contraste bien con el fondo
Prueba la legibilidad en distintos dispositivos

Longitud del título

Mantén los títulos cortos (menos de 50 caracteres)
Usa lenguaje orientado a la acción ("Contacto", "Get Support")

Descripciones

Mantén las descripciones concisas (1–2 frases)
Explica qué ocurre tras el envío

Texto del botón

Usa verbos claros ("Enviar", "Submit", "Contacto")
Mantenlo corto (1–3 palabras)

Ejemplos

Actualización mínima (solo colores)

{
  "background_color": "ffffff",
  "button_color": "007bff",
  "text_color": "333333"
}

Actualización de marca completa

{
  "title": "Contact Our Team",
  "description": "Have a question? We're here to help!",
  "background_color": "f8f9fa",
  "button_color": "28a745",
  "text_color": "212529",
  "logo_url": "https://example.com/logo.png",
  "button_text": "Enviar Mensaje",
  "field_name_label": "Full Nombre",
  "field_email_label": "Correo electrónico",
  "field_message_label": "Túr Mensaje",
  "field_name_placeholder": "Enter your name",
  "field_email_placeholder": "you@example.com",
  "field_message_placeholder": "Tell us how we can help..."
}